fix(Swagger): Fixed the Swagger documentation by adding custom tags to controllers and generating operation ids

cdavernas · cdavernas · commit f5f90c5018ea · 2022-11-04T16:37:03.000+01:00
WIP: will not build
diff --git a/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1ApplicationController.cs b/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1ApplicationController.cs
@@ -15,12 +15,15 @@
  *
  */
 
+using Microsoft.AspNetCore.Http;
+
 namespace Synapse.Apis.Management.Http.Controllers
 {
 
     /// <summary>
     /// Represents the <see cref="ApiController"/> used to manage the Synapse application
     /// </summary>
+    [Tags("Application")]
     [Route("api/v1/application")]
     public class V1ApplicationController
         : ApiController
diff --git a/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1AuthenticationDefinitionCollectionsController.cs b/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1AuthenticationDefinitionCollectionsController.cs
@@ -15,6 +15,7 @@
  *
  */
 
+using Microsoft.AspNetCore.Http;
 using ServerlessWorkflow.Sdk.Models;
 
 namespace Synapse.Apis.Management.Http.Controllers
@@ -23,6 +24,7 @@ namespace Synapse.Apis.Management.Http.Controllers
     /// <summary>
     /// Represents the <see cref="ApiController"/> used to manage authentication definition collections
     /// </summary>
+    [Tags("AuthenticationDefinitionCollections")]
     [Route("api/v1/resources/collections/authentications")]
     public class V1AuthenticationDefinitionCollectionsController
         : ApiController
diff --git a/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1CorrelationsController.cs b/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1CorrelationsController.cs
@@ -15,12 +15,15 @@
  *
  */
 
+using Microsoft.AspNetCore.Http;
+
 namespace Synapse.Apis.Management.Http.Controllers
 {
 
     /// <summary>
     /// Represents the <see cref="ApiController"/> used to manage correlation definitions
     /// </summary>
+    [Tags("Correlations")]
     [Route("api/v1/correlations")]
     public class V1CorrelationsController
         : ApiController
diff --git a/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1EventDefinitionCollectionsController.cs b/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1EventDefinitionCollectionsController.cs
@@ -15,6 +15,7 @@
  *
  */
 
+using Microsoft.AspNetCore.Http;
 using ServerlessWorkflow.Sdk.Models;
 
 namespace Synapse.Apis.Management.Http.Controllers
@@ -23,6 +24,7 @@ namespace Synapse.Apis.Management.Http.Controllers
     /// <summary>
     /// Represents the <see cref="ApiController"/> used to manage event definition collections
     /// </summary>
+    [Tags("EventDefinitionCollections")]
     [Route("api/v1/resources/collections/events")]
     public class V1EventDefinitionCollectionsController
         : ApiController
diff --git a/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1FunctionDefinitionCollectionsController.cs b/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1FunctionDefinitionCollectionsController.cs
@@ -15,6 +15,7 @@
  *
  */
 
+using Microsoft.AspNetCore.Http;
 using ServerlessWorkflow.Sdk.Models;
 
 namespace Synapse.Apis.Management.Http.Controllers
@@ -23,6 +24,7 @@ namespace Synapse.Apis.Management.Http.Controllers
     /// <summary>
     /// Represents the <see cref="ApiController"/> used to manage function definition collections
     /// </summary>
+    [Tags("FunctionDefinitionCollections")]
     [Route("api/v1/resources/collections/functions")]
     public class V1FunctionDefinitionCollectionsController
         : ApiController
diff --git a/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1OperationalReportsController.cs b/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1OperationalReportsController.cs
@@ -15,12 +15,15 @@
  *
  */
 
+using Microsoft.AspNetCore.Http;
+
 namespace Synapse.Apis.Management.Http.Controllers
 {
 
     /// <summary>
     /// Represents the <see cref="ApiController"/> used to manage application metrics
     /// </summary>
+    [Tags("OperationalReports")]
     [Route("api/v1/reports/operations")]
     public class V1OperationalReportsController
         : ApiController
diff --git a/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1SchedulesController.cs b/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1SchedulesController.cs
@@ -15,12 +15,15 @@
  *
  */
 
+using Microsoft.AspNetCore.Http;
+
 namespace Synapse.Apis.Management.Http.Controllers
 {
 
     /// <summary>
     /// Represents the <see cref="ApiController"/> used to manage schedules
     /// </summary>
+    [Tags("Schedules")]
     [Route("api/v1/schedules")]
     public class V1SchedulesController
         : ApiController
@@ -100,7 +103,7 @@ public async Task<IActionResult> PatchSchedule(Integration.Commands.Generic.V1Pa
         /// <param name="cancellationToken">A <see cref="CancellationToken"/></param>
         /// <returns>A new <see cref="IActionResult"/></returns>
         [HttpPut("{id}/trigger")]
-        [ProducesResponseType((int)HttpStatusCode.NoContent)]
+        [ProducesResponseType(typeof(Integration.Models.V1Schedule), (int)HttpStatusCode.OK)]
         [ProducesResponseType((int)HttpStatusCode.NotFound)]
         [ProducesResponseType((int)HttpStatusCode.Unauthorized)]
         [ProducesResponseType((int)HttpStatusCode.Forbidden)]
@@ -132,7 +135,7 @@ public async Task<IActionResult> SuspendSchedule(string id, CancellationToken ca
         /// <param name="cancellationToken">A <see cref="CancellationToken"/></param>
         /// <returns>A new <see cref="IActionResult"/></returns>
         [HttpPut("{id}/resume")]
-        [ProducesResponseType((int)HttpStatusCode.NoContent)]
+        [ProducesResponseType(typeof(Integration.Models.V1Schedule), (int)HttpStatusCode.OK)]
         [ProducesResponseType((int)HttpStatusCode.NotFound)]
         [ProducesResponseType((int)HttpStatusCode.Unauthorized)]
         [ProducesResponseType((int)HttpStatusCode.Forbidden)]
diff --git a/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1WorkflowActivitiesController.cs b/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1WorkflowActivitiesController.cs
@@ -15,12 +15,15 @@
  *
  */
 
+using Microsoft.AspNetCore.Http;
+
 namespace Synapse.Apis.Management.Http.Controllers
 {
 
     /// <summary>
     /// Represents the <see cref="ApiController"/> used to manage workflow activities
     /// </summary>
+    [Tags("WorkflowActivities")]
     [Route("api/v1/workflow-activities")]
     public class V1WorkflowActivitiesController
         : ApiController
diff --git a/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1WorkflowInstancesController.cs b/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1WorkflowInstancesController.cs
@@ -15,6 +15,7 @@
  *
  */
 
+using Microsoft.AspNetCore.Http;
 using System.Net.Mime;
 
 namespace Synapse.Apis.Management.Http.Controllers
@@ -23,6 +24,7 @@ namespace Synapse.Apis.Management.Http.Controllers
     /// <summary>
     /// Represents the <see cref="ApiController"/> used to manage workflow instances
     /// </summary>
+    [Tags("WorkflowInstances")]
     [Route("api/v1/workflow-instances")]
     public class V1WorkflowInstancesController
         : ApiController
diff --git a/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1WorkflowsController.cs b/src/apis/management/Synapse.Apis.Management.Http/Controllers/V1WorkflowsController.cs
@@ -15,6 +15,7 @@
  *
  */
 
+using Microsoft.AspNetCore.Http;
 using System.Net.Mime;
 
 namespace Synapse.Apis.Management.Http.Controllers
@@ -23,6 +24,7 @@ namespace Synapse.Apis.Management.Http.Controllers
     /// <summary>
     /// Represents the <see cref="ApiController"/> used to manage workflow definitions
     /// </summary>
+    [Tags("Workflows")]
     [Route("api/v1/workflows")]
     public class V1WorkflowsController
         : ApiController
diff --git a/src/apis/management/Synapse.Apis.Management.Http/Extensions/ISynapseApplicationBuilderExtensions.cs b/src/apis/management/Synapse.Apis.Management.Http/Extensions/ISynapseApplicationBuilderExtensions.cs
@@ -15,12 +15,14 @@
  *
  */
 
+using Microsoft.AspNetCore.Mvc.Controllers;
 using Microsoft.AspNetCore.OData;
 using Microsoft.AspNetCore.OData.NewtonsoftJson;
 using Microsoft.AspNetCore.OData.Query.Expressions;
 using Microsoft.AspNetCore.OData.Routing.Controllers;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.OpenApi.Models;
+using Neuroglia;
 using Newtonsoft.Json;
 using Newtonsoft.Json.Serialization;
 using Synapse.Apis.Management.Http.Services;
@@ -72,6 +74,12 @@ public static ISynapseApplicationBuilder UseHttpManagementApi(this ISynapseAppli
                 .AddApplicationPart(typeof(MetadataController).Assembly);
             synapse.Services.AddSwaggerGen(builder =>
             {
+                builder.CustomOperationIds(o =>
+                {
+                    if (!string.IsNullOrWhiteSpace(o.RelativePath) && o.RelativePath.StartsWith("odata")) return o.RelativePath;
+                    var action = (ControllerActionDescriptor)o.ActionDescriptor;
+                    return $"{action.ActionName}".ToCamelCase();
+                });
                 builder.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
                 builder.SwaggerDoc("v1", new OpenApiInfo
                 {
diff --git a/src/apps/Synapse.Server/Program.cs b/src/apps/Synapse.Server/Program.cs
@@ -73,6 +73,7 @@
     builder.DocExpansion(DocExpansion.None);
     builder.SwaggerEndpoint("/api/v1/doc/oas.json", "Synapse API v1");
     builder.RoutePrefix = "api/doc";
+    builder.DisplayOperationId();
 });
 app.MapControllers();
 app.MapGrpcService<SynapseGrpcManagementApi>();
diff --git a/src/core/Synapse.Application/Commands/Schedules/v1/V1ResumeScheduleCommand.cs b/src/core/Synapse.Application/Commands/Schedules/v1/V1ResumeScheduleCommand.cs
@@ -15,14 +15,16 @@
  *
  */
 
+using Neuroglia.Mediation;
+
 namespace Synapse.Application.Commands.Schedules
 {
     /// <summary>
     /// Represents the <see cref="ICommand"/> used to resume a <see cref="V1Schedule"/>
     /// </summary>
     [DataTransferObjectType(typeof(Integration.Commands.Schedules.V1ResumeScheduleCommand))]
     public class V1ResumeScheduleCommand
-        : Command
+        : Command<Integration.Models.V1Schedule>
     {
 
         /// <summary>
@@ -51,7 +53,7 @@ public V1ResumeScheduleCommand(string scheduleId)
     /// </summary>
     public class V1ResumeScheduleCommandHandler
         : CommandHandlerBase,
-        ICommandHandler<V1ResumeScheduleCommand>
+        ICommandHandler<V1ResumeScheduleCommand, Integration.Models.V1Schedule>
     {
 
         /// <summary>
@@ -73,14 +75,14 @@ public V1ResumeScheduleCommandHandler(ILoggerFactory loggerFactory, IMediator me
         protected IRepository<V1Schedule> Schedules { get; }
 
         /// <inheritdoc/>
-        public virtual async Task<IOperationResult> HandleAsync(V1ResumeScheduleCommand command, CancellationToken cancellationToken = default)
+        public virtual async Task<IOperationResult<Integration.Models.V1Schedule>> HandleAsync(V1ResumeScheduleCommand command, CancellationToken cancellationToken = default)
         {
             var schedule = await this.Schedules.FindAsync(command.ScheduleId, cancellationToken);
             if (schedule == null) throw DomainException.NullReference(typeof(V1Schedule), command.ScheduleId);
             schedule.Resume();
-            await this.Schedules.UpdateAsync(schedule, cancellationToken);
+            schedule = await this.Schedules.UpdateAsync(schedule, cancellationToken);
             await this.Schedules.SaveChangesAsync(cancellationToken);
-            return this.Ok();
+            return this.Ok(this.Mapper.Map<Integration.Models.V1Schedule>(schedule));
         }
 
     }
diff --git a/src/core/Synapse.Application/Commands/Schedules/v1/V1TriggerScheduleCommand.cs b/src/core/Synapse.Application/Commands/Schedules/v1/V1TriggerScheduleCommand.cs
@@ -23,7 +23,7 @@ namespace Synapse.Application.Commands.Schedules
     /// </summary>
     [DataTransferObjectType(typeof(Integration.Commands.Schedules.V1TriggerScheduleCommand))]
     public class V1TriggerScheduleCommand
-        : Command
+        : Command<Integration.Models.V1Schedule>
     {
 
         /// <summary>
@@ -52,7 +52,7 @@ public V1TriggerScheduleCommand(string scheduleId)
     /// </summary>
     public class V1TriggerScheduleCommandHandler
         : CommandHandlerBase,
-        ICommandHandler<V1TriggerScheduleCommand>
+        ICommandHandler<V1TriggerScheduleCommand, Integration.Models.V1Schedule>
     {
 
         /// <summary>
@@ -74,14 +74,14 @@ public V1TriggerScheduleCommandHandler(ILoggerFactory loggerFactory, IMediator m
         protected IRepository<V1Schedule> Schedules { get; }
 
         /// <inheritdoc/>
-        public virtual async Task<IOperationResult> HandleAsync(V1TriggerScheduleCommand command, CancellationToken cancellationToken = default)
+        public virtual async Task<IOperationResult<Integration.Models.V1Schedule>> HandleAsync(V1TriggerScheduleCommand command, CancellationToken cancellationToken = default)
         {
             var schedule = await this.Schedules.FindAsync(command.ScheduleId, cancellationToken);
             if (schedule == null) throw DomainException.NullReference(typeof(V1Schedule), command.ScheduleId);
             schedule.Trigger();
-            await this.Schedules.UpdateAsync(schedule, cancellationToken);
+            schedule = await this.Schedules.UpdateAsync(schedule, cancellationToken);
             await this.Schedules.SaveChangesAsync(cancellationToken);
-            return this.Ok();
+            return this.Ok(this.Mapper.Map<Integration.Models.V1Schedule>(schedule));
         }
 
     }
diff --git a/src/core/Synapse.Application/Commands/Workflows/v1/V1ScheduleWorkflowCommand.cs b/src/core/Synapse.Application/Commands/Workflows/v1/V1ScheduleWorkflowCommand.cs
@@ -78,24 +78,17 @@ public class V1ScheduleWorkflowCommandHandler
         /// <param name="mediator">The service used to mediate calls</param>
         /// <param name="mapper">The service used to map objects</param>
         /// <param name="workflows">The <see cref="IRepository"/> used to manage <see cref="V1Workflow"/>s</param>
-        /// <param name="cronJobScheduler">The service used to schedule CRON jobs</param>
-        public V1ScheduleWorkflowCommandHandler(ILoggerFactory loggerFactory, IMediator mediator, IMapper mapper, IRepository<V1Workflow> workflows, ICronJobScheduler cronJobScheduler) 
+        public V1ScheduleWorkflowCommandHandler(ILoggerFactory loggerFactory, IMediator mediator, IMapper mapper, IRepository<V1Workflow> workflows) 
             : base(loggerFactory, mediator, mapper)
         {
             this.Workflows = workflows;
-            this.CronJobScheduler = cronJobScheduler;
         }
 
         /// <summary>
         /// Gets the <see cref="IRepository"/> used to manage <see cref="V1Workflow"/>s
         /// </summary>
         protected IRepository<V1Workflow> Workflows { get; }
 
-        /// <summary>
-        /// Gets the service used to schedule CRON jobs
-        /// </summary>
-        protected ICronJobScheduler CronJobScheduler { get; }
-
         /// <inheritdoc/>
         public virtual async Task<IOperationResult> HandleAsync(V1ScheduleWorkflowCommand command, CancellationToken cancellationToken = default)
         {
@@ -124,7 +117,7 @@ public virtual async Task<IOperationResult> HandleAsync(V1ScheduleWorkflowComman
                     await this.Mediator.ExecuteAndUnwrapAsync(new V1CreateWorkflowInstanceCommand(workflow.Id, V1WorkflowInstanceActivationType.Cron, new(), null, true, null), cancellationToken);
                 }
             }
-            await this.CronJobScheduler.ScheduleJobAsync(workflow.Definition.Id!, cronExpression, timeZone, job, workflow.Definition.Start.Schedule.Cron?.ValidUntil, cancellationToken);
+            //await this.CronJobScheduler.ScheduleJobAsync(workflow.Definition.Id!, cronExpression, timeZone, job, workflow.Definition.Start.Schedule.Cron?.ValidUntil, cancellationToken);
             return this.Ok();
         }
 
diff --git a/src/core/Synapse.Application/Configuration/SynapseApplicationBuilder.cs b/src/core/Synapse.Application/Configuration/SynapseApplicationBuilder.cs
@@ -120,7 +120,6 @@ public virtual void Build()
             this.Services.AddSingleton<IHostedService>(provider => provider.GetRequiredService<WorkflowProcessManager>());
             this.Services.AddSingleton<IWorkflowRuntimeProxyFactory, WorkflowRuntimeProxyFactory>();
             this.Services.AddSingleton<IWorkflowRuntimeProxyManager, WorkflowRuntimeProxyManager>();
-            this.Services.AddSingleton<ICronJobScheduler, CronJobScheduler>();
             this.Services.AddHostedService<WorkflowScheduler>();
             this.Services.AddHostedService<WorkflowDefinitionFileMonitor>();
             this.Services.AddTransient(provider => provider.GetRequiredService<IEdmModelBuilder>().Build());
diff --git a/src/core/Synapse.Application/Services/CronJob.cs b/src/core/Synapse.Application/Services/CronJob.cs
diff --git a/src/core/Synapse.Application/Services/CronJobScheduler.cs b/src/core/Synapse.Application/Services/CronJobScheduler.cs
diff --git a/src/core/Synapse.Application/Services/WorkflowScheduler.cs b/src/core/Synapse.Application/Services/WorkflowScheduler.cs
diff --git a/src/core/Synapse.Infrastructure/Services/ICronJob.cs b/src/core/Synapse.Infrastructure/Services/ICronJob.cs
diff --git a/src/core/Synapse.Infrastructure/Services/ICronJobScheduler.cs b/src/core/Synapse.Infrastructure/Services/ICronJobScheduler.cs

Original file line number	Diff line number	Diff line change
`@@ -15,12 +15,15 @@`
`15`	`15`	`*`
`16`	`16`	`*/`
`17`	`17`
	`18`	`+using Microsoft.AspNetCore.Http;`
	`19`	`+`
`18`	`20`	`namespace Synapse.Apis.Management.Http.Controllers`
`19`	`21`	`{`
`20`	`22`
`21`	`23`	`/// <summary>`
`22`	`24`	`/// Represents the <see cref="ApiController"/> used to manage the Synapse application`
`23`	`25`	`/// </summary>`
	`26`	`+ [Tags("Application")]`
`24`	`27`	`[Route("api/v1/application")]`
`25`	`28`	`public class V1ApplicationController`
`26`	`29`	`: ApiController`