ensuring more detailed swagger

src/Altinn.Notifications/Altinn.Notifications.csproj

@@ -17,6 +17,8 @@
     <PackageReference Include="Azure.Security.KeyVault.Secrets" Version="4.5.0" />
     <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
     <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
+    <PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="6.5.0" />
+    <PackageReference Include="Swashbuckle.AspNetCore.Filters" Version="7.0.11" />
     <PackageReference Include="System.Drawing.Common" Version="7.0.0" />
     <PackageReference Include="System.Text.RegularExpressions" Version="4.3.1" />
   </ItemGroup>

src/Altinn.Notifications/Controllers/EmailNotificationOrdersController.cs

@@ -11,6 +11,9 @@
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 
+using Swashbuckle.AspNetCore.Annotations;
+using Swashbuckle.AspNetCore.Filters;
+
 namespace Altinn.Notifications.Controllers;
 
 /// <summary>
@@ -19,6 +22,9 @@ namespace Altinn.Notifications.Controllers;
 [Route("notifications/api/v1/orders/email")]
 [ApiController]
 [Authorize]
+[SwaggerResponse(401, "Caller is unauthorized")]
+[SwaggerResponse(403, "Caller is not authorized to access the requested resource")]
+
 public class EmailNotificationOrdersController : ControllerBase
 {
     private readonly IValidator<EmailNotificationOrderRequestExt> _validator;
@@ -38,10 +44,14 @@ public EmailNotificationOrdersController(IValidator<EmailNotificationOrderReques
     /// The API will accept the request after som basic validation of the request.
     /// The system will also attempt to verify that it will be possible to fulfill the order.
     /// </summary>
-    /// <returns>The registered notification order</returns>
+    /// <returns>The id of the registered notification order</returns>
     [HttpPost]
     [Consumes("application/json")]
-    public async Task<ActionResult<NotificationOrderExt>> Post(EmailNotificationOrderRequestExt emailNotificationOrderRequest)
+    [Produces("application/json")]
+    [SwaggerResponse(202, "The notification order was accepted", typeof(OrderIdExt))]
+    [SwaggerResponse(400, "The notification order is invalid", typeof(ValidationProblemDetails))]
+    [SwaggerResponseHeader(202, "Location", "string", "Link to access the newly created notification order.")]
+    public async Task<ActionResult<OrderIdExt>> Post(EmailNotificationOrderRequestExt emailNotificationOrderRequest)
     {
         var validationResult = _validator.Validate(emailNotificationOrderRequest);
         if (!validationResult.IsValid)

src/Altinn.Notifications/Controllers/OrdersController.cs

@@ -5,6 +5,9 @@
 
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.ModelBinding;
+
+using Swashbuckle.AspNetCore.Annotations;
 
 namespace Altinn.Notifications.Controllers;
 
@@ -14,6 +17,8 @@ namespace Altinn.Notifications.Controllers;
 [Route("notifications/api/v1/orders")]
 [ApiController]
 [Authorize]
+[SwaggerResponse(401, "Caller is unauthorized")]
+[SwaggerResponse(403, "Caller is not authorized to access the requested resource")]
 public class OrdersController : ControllerBase
 {
     private readonly IGetOrderService _getOrderService;
@@ -33,6 +38,9 @@ public OrdersController(IGetOrderService getOrderService)
     /// <returns>The order that correspons to the provided id</returns>
     [HttpGet]
     [Route("{id}")]
+    [Produces("application/json")]
+    [SwaggerResponse(200, "The notification order matching the provided id was retrieved successfully", typeof(NotificationOrderExt))]
+    [SwaggerResponse(404, "No order with the provided id was found")]
     public async Task<ActionResult<NotificationOrderExt>> GetById([FromRoute] Guid id)
     {
         string? expectedCreator = User.GetOrg();
@@ -57,7 +65,9 @@ public async Task<ActionResult<NotificationOrderExt>> GetById([FromRoute] Guid i
     /// <param name="sendersReference">The senders reference</param>
     /// <returns>The order that correspons to the provided senders reference</returns>
     [HttpGet]
-    public async Task<ActionResult<NotificationOrderListExt>> GetBySendersRef([FromQuery] string sendersReference)
+    [Produces("application/json")]
+    [SwaggerResponse(200, "The list of notification orders matching the provided senders ref was retrieved successfully", typeof(NotificationOrderListExt))]
+    public async Task<ActionResult<NotificationOrderListExt>> GetBySendersRef([FromQuery, BindRequired] string sendersReference)
     {
         string? expectedCreator = User.GetOrg();
         if (expectedCreator == null)
@@ -82,6 +92,9 @@ public async Task<ActionResult<NotificationOrderListExt>> GetBySendersRef([FromQ
     /// <returns>The order that correspons to the provided id</returns>
     [HttpGet]
     [Route("{id}/status")]
+    [Produces("application/json")]
+    [SwaggerResponse(200, "The notification order matching the provided id was retrieved successfully", typeof(NotificationOrderExt))]
+    [SwaggerResponse(404, "No order with the provided id was found")]
     public async Task<ActionResult<NotificationOrderWithStatusExt>> GetWithStatusById([FromRoute] Guid id)
     {
         string? expectedCreator = User.GetOrg();

src/Altinn.Notifications/Program.cs

@@ -1,4 +1,5 @@
 #nullable disable
+using System.Reflection;
 using System.Text.Json;
 using System.Text.Json.Serialization;
 
@@ -24,6 +25,9 @@
 using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;
 using Microsoft.IdentityModel.Tokens;
 
+using Swashbuckle.AspNetCore.Filters;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
 ILogger logger;
 
 string vaultApplicationInsightsKey = "ApplicationInsights--InstrumentationKey";
@@ -38,7 +42,12 @@
 ConfigureServices(builder.Services, builder.Configuration);
 
 builder.Services.AddEndpointsApiExplorer();
-builder.Services.AddSwaggerGen();
+builder.Services.AddSwaggerGen(c =>
+{
+    IncludeXmlComments(c);
+    c.EnableAnnotations();    
+    c.OperationFilter<AddResponseHeadersFilter>();
+});
 
 var app = builder.Build();
 app.SetUpPostgreSql(builder.Environment.IsDevelopment(), builder.Configuration);
@@ -62,7 +71,7 @@
 {
     var logFactory = LoggerFactory.Create(builder =>
     {
         builder
             .AddFilter("Altinn.Platform.Notifications.Program", LogLevel.Debug)
             .AddConsole();
     });
@@ -101,7 +110,7 @@
         // If not application insight is available log to console
         logging.AddFilter("Microsoft", LogLevel.Warning);
         logging.AddFilter("System", LogLevel.Warning);
         logging.AddConsole();
     }
 }
 
@@ -122,7 +131,7 @@
     services.AddSingleton(config);
     if (!string.IsNullOrEmpty(applicationInsightsConnectionString))
     {
         services.AddSingleton(typeof(ITelemetryChannel), new ServerTelemetryChannel() { StorageFolder = "/tmp/logtelemetry" });
 
         services.AddApplicationInsightsTelemetry(new ApplicationInsightsServiceOptions
         {
@@ -214,3 +223,17 @@
     ValidatorOptions.Global.LanguageManager.Enabled = false;
     services.AddSingleton<IValidator<EmailNotificationOrderRequestExt>, EmailNotificationOrderRequestValidator>();
 }
+
+void IncludeXmlComments(SwaggerGenOptions swaggerGenOptions)
+{
+    try
+    {
+        string xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
+        string xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
+        swaggerGenOptions.IncludeXmlComments(xmlPath);
+    }
+    catch (Exception e)
+    {
+        logger.LogWarning(e, "Program // Exception when attempting to include the XML comments file(s).");
+    }
+}