In today’s distributed environment and even the latest client-side development approaches tend to push for the creation and consumption of API-enabled services.
While APIs offer great advantages, in order to be effective they must be:
- Clearly and accurately documented
- Up-to-date with the latest changes
- Easy for developers to explore and test the API methods (both the expected input and the output)
One of the most popular formats for the documentation of APIs is the Swagger specification.
You can read more about Swagger here: http://swagger.io/
“Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.”
Below is a link to an simple example of a Pet Store API that has been documented with the Swagger specifications.
Now let’s create the documentation for an MVC API
that supports the Swagger specifications!
You can implement API documentation matching the Swagger specifications within your MVC API, by following a few simple steps:
Step #1. Install the nuget package “SwashBuckle” in your MVC web app
Step #2. Once installed, you can simply navigate to the swagger URL in your MVC app.
By default this is: http://(your project’s url)/swagger
Your new API documentation will automatically include:
- (1) A list of all API methods available (with both input model and response model)
- (2) The capability to perform requests to the API using the web UI
Step #3. Secure the documentation (if necessary).
The Swashbuckle nuget package supports Basic Authentication, an API key or OAuth2.
Step #4. Improve the auto-generated documentation using XML comments
Once you are up and going, you may want to improve the results of your documentation. This means that you can customize the documentation by:
- add comments, descriptions and explanations to your API methods,
You can extend the automatically created documentation by adding your own comments as shown below:
These comments end up showing up in the Swagger API documentation as follows:
Finally, explore the additional related Swagger nuget packages.
Swashbuckle offers additional nuget packages that extend the functionality of the core nuget package.
Some of the additional capabilities available to this nuget package include:
- Support for OData APIs
- Support for ASP.NET Core 1.0
This nuget package insures that your API documentation is always 100% up-to-date, clearly documented and provides developers with an easy way to test how they can expect to interact with your API methods.