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. Aggregate 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
urlas type the swagger-aggregator will download the microservice swagger by the provided url field;
- File: by specifying
fileas type the swagger-aggregator will take the microservice swagger configurations by the provided path field.
In both of them the user can specify a
prefix to place before.
In both of them, the user can specify an
includePaths and an
excludePaths to filter the paths to be accessible from outside. The filter will include first all the paths according to the object passed by
includePaths then the result will be filtered by the
Please be sure to validate the configuration with the following jsonschema before run the service, otherwise the microservice will not correctly start.
It is possible to transform paths and apply custom tags to them with an advanced configuration.
This configuration will transform any path matching
/myPath to two different paths
/my-path2 with the specified tags.
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.