The Swagger Aggregator service is responsible for aggregating the individual swaggers of all the microservices indicated in the configuration. He collects all paths from the specified microservice swaggers and merge them all on a single swagger definition. To correctly handle the possible rewrite of the gateways, this service can be configured to handle the swagger paths with the correct prefix.
This service allows you to always have the right version of documentation of your API. The aggregated documentation will be available in the API Portal.
Configure Swagger Aggregator directly from Console
This Microservice is configured via a configuration file similar to this:
First, the swagger-aggregator configuration needs the generic information like title, version and description, that will generically describe the API set provided by all microservices.
There are two ways to provide a description:
- using the field
description: requires a simple string;
- using the field
descriptionMarkdownFilePath: requires the path of a MarkDown file with the description of the swagger (if specified, the content will be shown in the Swagger UI instead of the description).
baseSwagger object contains the first-level configurations of the final merged swagger. Besides all the field defined by either OpenApi 2.0 or OpenApi 3.0 specifications, this object can contain a
prefix field that will be prepended to the paths of all the routes in the final merged swagger.
services array contains the URLs and files list from which retrieve the swaggers of every microservice; in details, there are two ways to retrieve a microservice swagger:
- URL: by specifying
typeproperty the swagger-aggregator will download the microservice swagger by the provided
urlproperty. For this service type the required properties will be
- File: by specifying
typeproperty the swagger-aggregator will take the microservice swagger configurations by the provided
pathproperty. For this service type the required properties will be
In both of them, the user must specify a
prefix to place before the url or the file path. Any string that begins with
/ is accepted.
Passing the string
prefix means that no prefix will be added to your service urls or paths.
In both service types, the user can specify
excludePaths optional properties to filter the routes to be accessible in the swagger documentation. The filter will include first all the routes according to the objects present in the
includePaths property, then the result will be filtered by the objects present in the
Both properties should be an array of objects and each object requires
In each object it is also possible to define a
verb property that specifies which verb of that specific path should be included/excluded.
Here is a list of the routes that will or not be shown in the aggregated swagger documentation based on the example above:
/pathToInclude-1/clientswith any route verb: this route will be shown since the first part of the route path is present in the includePaths array.
/pathToInclude-3with any route verb: this route will not be shown since the first part of the route path is not present in the includePaths array.
/pathToInclude-1/pathToExclude-1/managerswith any route verb: this route will not be shown since the first part of the route path is present in the excludePaths array.
getverb: this route will be shown since the route path precisely matches the one present in the includePaths array with the same verb.
postverb: this route will not be shown because, even if the route path precisely matches the one present in the includePaths array, the specified verb is different.
getverb: this route will not be shown because the route path does not precisely match the one present in the includePaths array, even if the specified verb is the same.
It is important to notice that the behaviour of these two properties changes depending on the presence of
verb property. If
verb property is not defined all sub-routes that match the
path property will be included/excluded.
verb property is defined, only the routes that exactly match the
verb property will included/excluded.
It is also possible to transform paths and apply custom tags to them with
Here is a list of the routes that will or not be transformed in the aggregated swagger documentation based on the example above:
getverb: this route will be transformed into two different routes
/my-path2with the specified tags and
deleteverb: this route will be transformed into another route
Some other custom tagtag and
/yourPathwith any verb: this route will not be transformed since it does not match any transformPath.
getverb: this route will be transformed into another route
Some other custom tagtag and
getverb. It will not be transformed into
/my-path/customersbecause it does not exactly match
It is important to notice that the behaviour of
transformPaths property changes depending on the presence of
verbsToTransform property. If
verbsToTransform property is not defined all sub-routes that match the
path property will be transformed.
verbsToTransform property is defined, only the routes that exactly match the
verb property will transformed.
Please be sure to validate the configuration with the following jsonschema before run the service, otherwise the microservice will not correctly start.
For additional information about the more advanced properties that can be defined in swagger-aggregator configuration (e.g.,
subSwaggers property) visit this page.
The two main APIs exposed by this service are:
/swagger/json: it gives the JSON that aggregates the swagger definitions (specification OpenApi 2.0) of the microservices listed in configuration.
/openapi/v3/json: the same as above but the specification is OpenApi 3.0.
The service also responds with the swagger static website at the path
/swagger/ (only OpenApi 2.0 v2 specification).
If you request for OpenAPI 3.0 definitions you will get OpenApi 2.0 definitions converted, the other way around you won't get the documentation for services that expose 2.0 definitions.