Swagger Documentation Tutorial
This tutorial and demo project will show you how to add, set up, configure, and verify Swagger documentation to your developer WebApi project.
Swashbuckle and Swagger are two popular tools used for generating developer documentation for web APIs. Swashbuckle is a package that can be added to an ASP.NET Core web API project to integrate the Swagger UI. It has three main components: Swashbuckle.AspNetCore.Swagger, which is a Swagger object model and middleware to expose SwaggerDocument objects as JSON endpoints; Swashbuckle.AspNetCore.SwaggerGen, which is a Swagger generator that builds SwaggerDocument objects directly from your routes, controllers, and models; and Swashbuckle.AspNetCore.SwaggerUI, which is an embedded version of the Swagger UI tool. It interprets Swagger JSON to build a rich, customizable experience for describing the web API functionality. Swagger (OpenAPI) is a language-agnostic specification for describing REST APIs. It allows both computers and humans to understand the capabilities of a REST API without direct access to the source code. Its main goals are to minimize the amount of work needed to connect decoupled services. ¹³⁴
GitHub Project Repo
https://github.com/kathleenwest/Conto...
Project Series - Azure Virtual Machine Web App Demo (5 Episodes) See Link Below
• Swagger Documentation Tutorial
Script
This is how we tell Swagger to utilize the XML comments in our code.
Here is an example of an XML code comment for an API method.
This is how it looks in our Swagger documentation UI display.
There is one more step to do for this feature to work.
In the project properties, we must specify that XML comments be exported to a documentation file and specify the file name.
The next step is to add custom operational identifiers. These are descriptive API method names that are needed for reference and to build clients.
Here is an example of a custom operational identifier in our JSON swagger reference.
When we build a client for the demo, we reference this file.
Here is an example of our demo HttpClient utilizing the API operational identifier.
The final step for configuring the swagger generator is to add support for JsonPatch.
The last step is to configure Swagger to show its UI but only if we are running in development, not production.
You will need to add a custom environment name and value to the launch profile. The name and values must be spelled as shown. This step is critical to launch the SwaggerUI. Developers run their applications locally to generate Swagger documentation and test their API work.
Here is the final result and demo of our Swagger configuration.
Notice that we configured to only accept json and the swagger documentation reflects all our configurations.
This video is part of a series that discusses a simple demo web API. See the links in the description for the source code and other videos.
Source: Conversation with Bing, 11/10/2023
(1) Get started with Swashbuckle and ASP.NET Core. https://learn.microsoft.com/en-us/asp....
(2) ASP.NET Core web API documentation with Swagger / OpenAPI. https://learn.microsoft.com/en-us/asp....
(3) What is Swagger, Swashbuckle and Swashbuckle UI. https://stackoverflow.com/questions/4....
(4) Improve the developer experience of an API with Swagger documentation .... https://learn.microsoft.com/en-us/tra....