Adding Implementation notes to Swagger UI via Swashbuckle Attributes

While working on an API Application, I was reviewing the documentation from Azure regarding the customization options. In that article, you can learn how the generated Swagger document can be customized using XML Comments or attributes.

As I was learning more about the process, I came across an article by Taiseer Joudeh that discusses in-depth the XML Comment integration with Swashbuckle. What I noticed is that the XML Comments provide more information that just Response Types. Taiseer has a terrific image that shows where XML Comment elements end up in the Swagger UI.

Since the Swashbuckle extensibility approach is IOperationFilters and Attributes, I created a SwaggerImplementationNotesAttribute and a companion IOperationFilter.

First, a simple Attribute with a property for the Implementation notes:

Then, a Swashbuckle IOperation filter to add the ImplementationNotes property value into the Swagger document:

Once these are added to my project, I can decorate my WebAPI methods with the Swagger-related attributes:

// GET: Orders/5
[SwaggerResponse(HttpStatusCode.OK, "", typeof(Order))]
[SwaggerResponse(HttpStatusCode.NotFound)]
[SwaggerImplementationNotes("Returns order with specified OrderId.")]
public async Task<IHttpActionResult> Get(string id)  
{
}

References: I found the following helpful.

comments powered by Disqus