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.