API Documentation for ASP.NET API with Swagger
Why API Documentation?
API documentation helps your customers of your services better understand your product and how to use it. Once dashboards are enabled, it also gives them a clean environment to play with your APIs, and understand its behaviour in action before they start coding against it.
On top of that, there are scenarios in which having API documentation makes it technically easier for you to set up your environment. A good example is when you need API specification to set up your gateways (such as Azure API Manager), and instead of setting up http actions supported by the gateway, you simply import your documentation, and with a click of a button, all supported actions by your API are imported to the gateway.
By looking at the above documentation (Figure 1), you can see find the some background information about the API, all the paths (actions) this API supports along with some summary and the responses you should expect from this API in different scenarios.
When you stood up your API gateway, you will also get a developer portal out of the box for the consumers of your API to understand and play with your APIs. This is pretty handy and saves you a lot of time for something that you need for your clients.
Also, you get all that with a customised branding under your own domain.
By the way, this topic belongs to the series to set up an Asp.NET API for production use.
- API Route Versioning
- Configuration Management
- Secret Management
- Monitoring
- Database
- Documentation
- CORS
- Request Validation
- Global Exception Handling
- URL Rewriting
- Deploy .NET API to Azure App Service
Configuration
1. Packages
To enable documentation for our API, I am using Swashbuckle library. Below is the list of packages you will need for this purpose:
2. Services
There are two places you need to apply Swagger configuration in your API, one in Services, and the other in the middleware configuration. Starting with the Services, here is a sample of what you need:
A few points about this snippet:
- It provides some basic information about the developer of the API, links to terms, policies, and also support teams.
- It uses the standards comments we use on our methods and inject the documentation, so we don’t have to provide separate comments for this purpose. The only thing you do is to make sure each endpoint gets shipped with sufficient level of inline documentation like below:
- It provides some information on the security requirements and how to provide them, in our case we need JWT (Bearer) token.
- We also need to provide some options on how to generate the docs, and then inject it into our Dependency Injection pool of services:
Note
Configuration, plumbing and troubleshooting your software foundation take a considerable amount of time in your product development. Consider using Pellerex which is a complete foundation for your enterprise software products, providing source-included Identity and Payment functions across UI (React), API (.NET), Pipeline (Azure DevOps) and Infrastructure (Kubernetes).
3. Middleware
The next place to apply configuration is at the middleware pipeline, in which we provide the generated documentation json file to the requests asking for it. We will serve that file at /swagger/v1/swagger.json. Find the complete snippet which will be called during the middleware configuration below:
Route Versioning is Supported Here
Please note, this guide assumes you have enabled route versioning for your API, and hence you are able to access documentation for all the supported versions of your routes (v1, v2, etc.). To read more about how you enable route versioning for your API, visit Enable route versioning for ASP.NET 5.0 Web APIs.
Pellerex Foundation: For Your Next Enterprise Software
How are you building your current software today? Build everything from scratch or use a foundation to save on development time, budget and resources? For an enterprise software MVP, which might take 8–12 months with a small team, you might indeed spend 6 months on your foundation. Things like Identity, Payment, Infrastructure, DevOps, etc. they all take time, while contributing not much to your actual product. These features are needed, but they are not your differentiators.
Pellerex does just that. It provides a foundation that save you a lot development time and effort at a fraction of the cost. It gives you source-included Identity, Payment, Infrastructure, and DevOps to build Web, Api and Mobile apps all-integrated and ready-to-go on day 1.
Check out Pellerex and talk to our team today to start building your next enterprise software fast.
