Repository files navigation

Given 2 existing public APIs athttps://wizard-world-api.herokuapp.com/ andhttps://date.nager.at/ (for instance), we can configure the aggregator as follows:

@BeanOpenApiAggregatorSpecsspecs() {returnnewOpenApiAggregatorSpecs().spec(newSpec("https://date.nager.at/swagger/v3/swagger.json").replace("/api/v3","/dates")).spec(newSpec("https://wizard-world-api.herokuapp.com/swagger/v1/swagger.json").prefix("/wizards"));}

The aggregator will then expose a spec that combines the two APIs. The Wizards API will be prefixed with/wizards and the Dates API will be prefixed with/dates (with an additional removal of the/api/v3 prefix from the backend). The sample applicationGatewayApplication does this and also exposes the APIs via a Spring Cloud Gateway, so the paths match the aggregated spec. You can run it with./mvnw spring-boot:test-run and browse the spec athttp://localhost:8080/v3/api-docs.

Features:

• Spec conversion. If any of the specs is Swagger (OpenAPI 2.0) instead of OpenAPI 3.0 the aggregator will automatically convert it to OpenAPI 3.0. OpenAPI 3.1 is not supported yet, but it probably wouldn't be hard.
• Spec filtering. You can apply arbitrary filters to component specs, and to the aggregated result. For instance, you can remove theinfo section from the aggregated spec, or remove thepaths section from the Wizards API spec.
• SpringDoc integration. The aggregator uses the SpringDoc-generated spec as a base if it exists, so the application can provide its own endpoints and have them automatically added. Once SpringDoc is on the classpath the spec endpoint at/v3/api-docs is configured through the normal SpringDoc options (the endpoint created by this library backs off).
• Convenience methods for common filters. For instance, you can add path prefixes (as in the example above), rename operations, or rename schema objects. Cross references are updated automatically.
• External configuration. Setspring.openapi.base.* to be anOpenAPI spec that will be merged with the aggregated spec. This is useful for adding info, or global security definitions, for instance. And setspring.openapi.aggregator.path to configure the HTTP endpoint path (default/v3/api-docs). Seeapplication.yml in the tests for an example.