In the advanced tab of the Console Design section you can configure the Swagger Aggregator in advanced mode.
The advanced configuration allows managing how the swagger API are exposed. Examples of possible configurations are:
Create further custom routes
Rewrite swagger routes to match different specifications depending on the context
Define sub-swaggers to expose only a subset of the whole API
Collect and combine swaggers from other services to expose them in a single interface as a whole.
This configuration affects the API documentation available in the API Portal.
You can configure files directly from the Console: go to the Design area and click on the
Advanced tab, from the list expand
swagger-aggregator item. You have to edit the
swagger-aggregator.json file only.
Below are reported the properties that can be configured and how they can be employed to customize the Swagger Aggregator functionalities.
prefix to add to all paths a prefix. This feature may be useful when using multiple API Gateway or when having a custom reverse proxy before your project.
serviceUrlsBefore to add custom services from which retrieve the swaggers before the ones generated by the console. Use
serviceUrlsAfter to add services after the others.
Both properties are array where each object can have the following properties:
url: by specifying Url as type the swagger-aggregator will download the microservice swagger by the provided
file: by specifying file as type the swagger-aggregator will take the microservice swagger configurations by the provided
path: microservice swagger url/file path
prefix(optional): the prefix
In both of them, the user can specify an
includePaths and an
excludePaths array, useful to filter the paths that are 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
subswagger object to define, as described briefly above, a set of sub-swaggers that represents a limited view on all the API that services expose within a project.
There are many reasons to enable this feature, although they are usually such to cluster different endpoints under specific tags or to group routes so that they can be encapsulated into other projects.
Each element must be defined by
<reference-name>.json key,that can be used as a handle in the urlsBefore to select which group should be exposed in other projects swaggers, and can include the following properties:
name: represents the name associated to the group in the swagger interface.
tagName: represents the name under which all the routes that match the expression are grouped.
In order to exploit the expression function depending on different contexts, three JS variables are provided to support the filtering process:
method: it represents which HTTP method can be used to call a specific route
path: it represents the path called for a specific route
tags: it is the list of tags that decorates a specific route
Here is provided an example of what a sub-swagger.conf configuration file might look likes:
baseSwagger object to define custom paths following OpenAPI specification.