feat: POC on swagger docs for the exception api

application/CohortManager/src/Functions/ExceptionHandling/UpdateException/Program.cs

@@ -6,6 +6,8 @@
 using HealthChecks.Extensions;
 using Model;
 using NHS.Screening.UpdateException;
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Abstractions;
+using Microsoft.Azure.Functions.Worker.Extensions.OpenApi;
 
 var host = new HostBuilder()
     .AddConfiguration<UpdateExceptionConfig>(out UpdateExceptionConfig config)
@@ -15,6 +17,7 @@
     .ConfigureFunctionsWorkerDefaults()
     .ConfigureServices(services =>
     {
+        services.AddSingleton<IOpenApiHttpTriggerContext, OpenApiHttpTriggerContext>();
         services.AddSingleton<ICreateResponse, CreateResponse>();
         // Register health checks
         services.AddBasicHealthCheck("UpdateException");

application/CohortManager/src/Functions/ExceptionHandling/UpdateException/UpdateException.cs

@@ -9,6 +9,9 @@ namespace NHS.CohortManager.ExceptionService;
 using Model;
 using Common;
 using DataServices.Client;
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Enums;
+using Microsoft.OpenApi.Models;
 
 public class UpdateException
 {
@@ -27,6 +30,47 @@ public UpdateException(
     }
 
     [Function("UpdateException")]
+    //[OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, In = OpenApiSecurityLocationType.Header, Name = "x-functions-key")]
+    [OpenApiOperation(operationId: "UpdateExceptionRecord",
+        Summary = "Updates an exception record with ServiceNow information",
+        Description = "Updates an existing exception record with ServiceNow ticket number and timestamp",
+        Visibility = OpenApiVisibilityType.Important)]
+    /*[OpenApiParameter(
+        name: "x-functions-key",
+        In = ParameterLocation.Header,
+        Required = true,
+        Type = typeof(string),
+        Description = "Function authorization key")]*/
+    [OpenApiRequestBody(
+        contentType: "application/json",
+        bodyType: typeof(UpdateExceptionRequest),
+        Description = "The exception update request containing ServiceNow number",
+        Required = true)]
+    [OpenApiResponseWithBody(
+        statusCode: HttpStatusCode.OK,
+        contentType: "application/json",
+        bodyType: typeof(string),
+        Description = "Successfully updated the exception record")]
+    [OpenApiResponseWithBody(
+        statusCode: HttpStatusCode.BadRequest,
+        contentType: "application/json",
+        bodyType: typeof(string),
+        Description = "Invalid ExceptionId provided.")]
+    [OpenApiResponseWithBody(
+        statusCode: HttpStatusCode.NoContent,
+        contentType: "application/json",
+        bodyType: typeof(string),
+        Description = "No exception found with the supplied exception id")]
+    [OpenApiResponseWithBody(
+        statusCode: HttpStatusCode.InternalServerError,
+        contentType: "application/json",
+        bodyType: typeof(string),
+        Description = "Internal server error occurred")]
+    /*[OpenApiResponseWithBody(
+    statusCode: HttpStatusCode.Unauthorized,
+    contentType: "application/json",
+    bodyType: typeof(string),
+    Description = "Invalid or missing function key")]*/
     public async Task<HttpResponseData> RunAsync([HttpTrigger(AuthorizationLevel.Anonymous, "put")] HttpRequestData req)
     {
         _logger.LogInformation("Processing request to update ServiceNow number in exception management table.");
@@ -72,6 +116,7 @@ public async Task<HttpResponseData> RunAsync([HttpTrigger(AuthorizationLevel.Ano
         {
             _logger.LogError(ex, "An unexpected error occurred.");
             return _createResponse.CreateHttpResponse(HttpStatusCode.InternalServerError, req);
+            //return _createResponse.CreateHttpResponse(HttpStatusCode.InternalServerError, req, "", new ErrorResponse { Message = "An unexpected error occurred", Details = ex.Message });
         }
     }
 
@@ -102,3 +147,4 @@ private static void UpdateExceptionRecord(ExceptionManagement exceptionData, Upd
         exceptionData.ServiceNowCreatedDate = DateTime.Now;
     }
 }
+

application/CohortManager/src/Functions/ExceptionHandling/UpdateException/UpdateException.csproj

@@ -10,6 +10,7 @@
   <ItemGroup>
     <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.19.0" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.0.13" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.OpenApi" Version="1.5.1" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.15.1" />
     <PackageReference Include="Microsoft.Data.SqlClient" Version="5.2.0" />
     <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" Version="9.0.3" />

application/CohortManager/src/Functions/Shared/Common/Interfaces/ICreateResponse.cs

@@ -2,9 +2,11 @@ namespace Common;
 
 using System.Net;
 using Microsoft.Azure.Functions.Worker.Http;
+using Model;
 
 public interface ICreateResponse
 {
     public HttpResponseData CreateHttpResponse(HttpStatusCode statusCode, HttpRequestData httpRequestData, string responseBody = "");
+   // public HttpResponseData CreateHttpResponse(HttpStatusCode statusCode, HttpRequestData req, string responseBody = "", ErrorResponse? errorResponse = null);
     public Task<HttpResponseData> CreateHttpResponseWithBodyAsync(HttpStatusCode statusCode, HttpRequestData requestData, string responseBody);
 }

application/CohortManager/src/Functions/Shared/Model/Model.csproj

@@ -8,6 +8,7 @@
   </PropertyGroup>
 
   <ItemGroup>
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.OpenApi" Version="1.5.1" />
     <PackageReference Include="ParquetSharp" Version="17.0.0-beta1" />
   </ItemGroup>
 

application/CohortManager/src/Functions/Shared/Model/UpdateExceptionRequest.cs

@@ -1,7 +1,13 @@
 namespace Model;
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
+using System.ComponentModel.DataAnnotations;
 
 public class UpdateExceptionRequest
 {
+    [OpenApiProperty(Description = "The ID of the Exception to update")]
+    [Required]
     public string ExceptionId { get; set; }
+
+    [OpenApiProperty(Description = "ServiceNow ticket number (optional)")]
     public string? ServiceNowNumber { get; set; }
 }