Nowadays, a good API should provide documentation, and there are different tools to succeed in it. A swagger is a tool that was created to help us prepare documentation for our API and allows consumers to try and start using it efficiently.
Let’s clarify what the difference between OpenAPI and Swagger is?
OpenAPI is a standard format to define structure and syntax REST APIs
A swagger is a tool that allows the implementation of OpenAPI.
For .net developers, two packages provide the functionality to build the documentation:
- NSwag
- Swashbuckle
In this article, we will look at the basic configuration for one of them called NSwag. They both have pretty similar structures. And both of them generate documentation relying on API code. As developers, we don`t need to do anything else except writing well-known code for your API endpoints. Providing a proper configuration is enough, and NSwag will pick up all info directly from controllers.
Initial setup
First, what you need to add is the NuGet package:
dotnet add package NSwag.AspNetCore
After installing the package, let`s configure swagger documentation. In the Startup file, we have to add swagger documentation service to the, and we need to call AddSwaggerDocument with proper configuration.
The main parameters which we need to specify are:
Title — title for the swagger document
Version — allows specifying documentation`s version
Commonly, an authorization mechanism protects API, and the swagger tool allows you to specify how authorization will be provided and allows you to set it up.
DocumentProcessors — gives the ability to provide security tokens in request. We need to add SecurityDefinitionAppender in code to achieve it.
The final version will look like this:
cs
services.AddSwaggerDocument(document => {
document.Title = "Project API";
document.Version = "v1";
document.DocumentProcessors.Add(
new SecurityDefinitionAppender("JWT Token", new OpenApiSecurityScheme
{
Type = OpenApiSecuritySchemeType.ApiKey,
Description = "JWT Token",
Name = "Authorization",
In = OpenApiSecurityApiKeyLocation.Header
})
);
document.OperationProcessors.Add(new OperationSecurityScopeProcessor("JWT Token"));
});
The next step will be to configure ApplicationBuilder to use OpenAPI and UI:
`cs
OpenApiSchema[] schemes = new[] {
OpenApiSchema.Http,
OpenApiSchema.Https
};
app.UseOpenApi(s => {
s.Path = "api/swagger/{documentName}/swagger.json";
s.PostProcess = (document, request) => { document.Schemes = schemes; };
});
app.UseSwaggerUi3(s => {
s.DocumentPath = "api/swagger/{documentName}/swagger.json";
s.Path = $"/api/swagger/ui";
});
`
Conclusion
It`s pretty simple to configure swagger documentation for API and provide convenient UI for consumers who will use it. When you start a new project, try to give a convenient way for consumers to call your API, and swagger will be a good choice.
Any questions or comments? Ping me on LinkedIn or comment below. And if you liked this post, please give it a clap and share it with all of your friends.
Twitter: https://twitter.com/KyliaBoy
Linkedin: https://www.linkedin.com/in/andrew-kulta/
More articles you can find at:
https://blog.akyltech.com/
Top comments (0)