Customizing auto generated Swagger definitions

Question

I have swagger setup so that it generates the open Api Specification & Swagger Ui on project startup using NSwag based on the controllers in my WebApi. I would like to enhance the swagger Ui to include

• A summary/description for each endpoint
• Example parameter inputs for endpoints that require them
• Example request body for POST calls
• An example access token that can be used only in the swagger documentation to easily authenticate and be able to try everything out (a bit like in this example https://petstore.swagger.io/)

I'm new to NSwag and unsure how to approach adding these enhancements to my code, like where to add them, what i need to use (annotations on controllers? XML comments? another way?) I've tried editing the specification in 'Swagger Editor' but don't see how this can be the way to go since this gets re-generated on every application startup.

I've read the NSwag documentation but that seems to be all about adding the ASP.NET Core middleware, which I already have configured.

Edit: I now have a description at the top of the page, and have been able to add an example with the remarks tag in XML comments - is there a more elegant way to do this rather than using XML comments?

Answer 1

Figured this out now, ended up using operation processors to configure the Swagger UI/OpenApi endpoint summary, request examples, path parameter example values and the possible UI response codes

There isn't a lot of documentation online for doing it this way (all i could find was the XML comment way of doing it so this took a lot of trial and error to get this working)

Posting my solution here for anyone else who would prefer not to clutter up their controllers with XML comments. (Note: this solution is available in asp.net core 3.1, unsure about other versions)

1. Apply OpenApiOperationProcessor attribute to the controller action

[HttpPut("password")][OpenApiOperationProcessor(typeof(ResetPasswordOpenApiProcessor))]
public async Task<IActionResult> ResetPassword(ResetPasswordCommand request)
{
   await Mediator.Send(request);
   return Accepted();
}

2. Create the Operation Processor inheriting from IOperationProcessor and code the SwaggerUI customizations

Example below;

public class ResetPasswordOpenApiProcessor : IOperationProcessor
{
     public bool Process(OperationProcessorContext context)
     {
         context.OperationDescription.Operation.Summary = "Forgotten Password";
         context.OperationDescription.Operation.Description = "Sends a password reset email to the user with the provided email address.";

         context.OperationDescription.Operation.Parameters.Add(
                new NSwag.OpenApiParameter
             {
                 Kind = NSwag.OpenApiParameterKind.Body,
                 Description = "Forgotten Password Example",
                 Schema = new NJsonSchema.JsonSchema
                 {
                     Example = new ResetPasswordCommand()
                     {
                         Email = $"existingEmail@test.com"
                     }
                 }
             });

        context.OperationDescription.Operation.Responses.Clear();

        context.AddSuccessfulResponse(StatusCodes.Status202Accepted, "Password reset request accepted");
        context.AddBadRequestResponse();
        context.AddUnauthorizedResponse();
        context.AddInternalServerErrorResponse();

        return true;
    }
}