Contributing to MMLib.SwaggerForOcelot library for gateway itself documentation
Microservices, also know as microservice architecture, is an architecture that consists of many services which have the responsibility of a single function. In this architecture style, a client application should have access to associated microservices. This access can be made separately which means every request has to be processed and evaluated through the services. Therefore, the client application would require making multiple requests for a single operation. This situation can potentially cause bottlenecks, especially in large, complex enterprise-level service architectures. One of the ways to prevent or manage this bottleneck is to use the API Gateway.
API Gateway pattern provides a gateway service that provides a single entry point for a specific microservice group. Gateway service can be thought of as a facade pattern (in object-oriented design) implemented in a distributed system. It is located between client applications and microservices and has many features such as routing, request aggregation, load balancing, and so on. I recommend you to read the document in the link below for detailed information.
API documentation is a significant part of development in microservice architectures. SwaggerUI comes in help which is commonly used for documenting APIs. It has very useful features such as automatic OpenAPI file generation, versioning, and so on. To get more detail about Swagger:
Swashbuckle.AspNetCore is a widely used library to generate swagger documentation for an API written using the .NET Core framework. It has three main components: a middleware to expose document objects as JSON endpoints, a generator to build documents, and a UI tool to visualize generated documents.
So, API Gateways also requires proper and detailed documentation. This article is about the API documentation of Ocelot API Gateway. Ocelot is an open-source project based ASP.NET Core. It is scalable, lightweight, and provides many features such as routing and authentication.
SwaggerForOcelot library is a very useful library that combines two great projects: Swashbuckle.AspNetCore and Ocelot.
It allows you to view and use swagger documentation for downstream services directly through the Ocelot project. Accessing directly via http://ocelotprojecturl:port/swagger provides documentation for downstream services configured in ocelot.json
API gateway has endpoints for its features which include request aggregation, which are needed to be documented. Conveniently MMLib.SwaggerForOcelot library has a very simple option to include the gateway’s own documentation to NuGet package version 4.1.0.
services.AddSwaggerForOcelot(Configuration,
(o) =>
{
o.GenerateDocsForGatewayItSelf = true;
});In our implementations, we required some features about gateway documentation, which were missing. A couple of contributions have been made to the project for these features and they are released with version 4.4.0.
The first contribution is the feature to add XML summaries on the swagger document. Swashbuckle.AspNetCore has an option that gets XML documentation as output files. Therefore, we have extended the library with this functionality. As a result of this extension, GenerateDocsForGatewayItSelf is no longer just a boolean property.
A method with that name is available and it takes several options to give you a string array that contains required XML documentation output files to FilePathsForXmlComments property.
services.AddSwaggerForOcelot(Configuration,
(o) =>
{
o.GenerateDocsForGatewayItSelf(opt =>
{
opt.FilePathsForXmlComments = { "MyAPI.xml" };
}
});Another required feature was a DocumentFilter option of Swashbuckle.AspNetCore library. Some endpoints may not be required to be included in the swagger documentation. In this case, swagger allows us to filter documents by implementing IDocumentFilter interface. DocumentFilter option is also available in this version and it can be used like below.
services.AddSwaggerForOcelot(Configuration,
(o) =>
{
o.GenerateDocsForGatewayItSelf(opt =>
{
opt.DocumentFilter<MyDocumentFilter>();
}
});So, why we need a document filter? When you include the documentation for the ocelot gateway itself, you will see that there are two controllers in the swagger documentation by default. Therefore, the code shown below has been added as a document filter to remove default controllers from swagger:
public class MyDocumentFilter : IDocumentFilter
{
string[] _ignoredPaths = { “/configuration”, “/outputcache/{region}” }; public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
foreach (var ignorePath in _ignoredPaths)
{
swaggerDoc.Paths.Remove(ignorePath);
}
}
}
The last feature is to add a security option to the swagger for the gateway itself. We usually provide authenticated access to our APIs. Basically, an authorization header is used to place a security token
services.AddSwaggerForOcelot(Configuration,
(o) =>
{
o.GenerateDocsForGatewayItSelf(opt =>
{
opt.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
{
Description = @"JWT Authorization header using the Bearer scheme. Enter 'Bearer' [space] and then your token in the text input below. Example: 'Bearer 12345abcdef'",
Name = "Authorization",
In = ParameterLocation.Header,
Type = SecuritySchemeType.ApiKey,
Scheme = "Bearer"
});
opt.AddSecurityRequirement(new OpenApiSecurityRequirement()
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
},
Scheme = "oauth2",
Name = "Bearer",
In = ParameterLocation.Header,
},
new List<string>()
}
});
});
});After adding security definition and requirement options, swagger UI will has an authorization option like this:
These are the features that we need in our projects. Thank you to the authors of this useful open source project and would like to thank you MMLib.SwaggerForOcelot contributors for allowing me to contribute to the library.
The library is available at https://www.nuget.org/packages/MMLib.SwaggerForOcelot/
Thanks for reading.
