bootique-swagger: a REST service to dynamically generate OpenAPI specifications as either JSON or YAML. Combines metadata from annotated API resources within the application with static API descriptors to produce application-specific API specs.
bootique-swagger-ui: embeddable Swagger web UI to visualize and interact with API specifications. Supports both OpenAPI 3 and legacy Swagger 2 specifications.
TODO: the examples below are based on the yet unreleased Bootique 2.0, and are only available as snapshots.
<dependencyManagement> <dependencies> <dependency> <groupId>io.bootique.bom</groupId> <artifactId>bootique-bom</artifactId> <version>2.0-SNAPSHOTS</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>
Publishing API Specifications
bootique-swagger can generate API specification by combining multiple YAML/JSON specifications as well as
endpoint metadata (class/methods signatures, JAX-RS annotations such as
@GET, etc. and
Swagger annotations. To include one or
more specification resources, add the following dependency:
<dependency> <groupId>io.bootique.swagger</groupId> <artifactId>bootique-swagger</artifactId> </dependency>
And then configure the layout and the sources of the specs:
swagger: specs: # arbitrary name of a spec endpoint... Multiple specs at different URLs are supported default: # desired URL paths of JSON and YAML resources. Resolved relative to Jersey root URL pathJson: "model/openapi.json" pathYaml: "model/openapi.yaml" # where the spec sources are spec: "classpath:main-openapi.yml" overrideSpec: "classpath:extra-openapi.yml" resourcePackages: - "com.example.api" resourceClasses: - "com.example.Api"
You can use any combination of "spec", "overrideSpec", "resourcePackages" and "resourceClasses". "spec" is usually appropriate for "design-first" approach, "resourcePackages" and "resourceClasses" - for the "code-first". "overrideSpec" can be used with both to add extra information. The order of loading is:
- "resourcePackages" / "resourceClasses": This provides the metadata collected from endpoint Java classes and annotations.
- "spec": This is a YAML or JSON file. Combined with "1", overriding any common properties.
- "overrideSpec": This is a YAML or JSON file. Combined with "1" and "2", overriding any common properties in both.
Now, when you run the app, you should be able to access the specs at the URLs similar to these:
Bootique integrates Swagger browser UI to be able to view and interact with the API specs:
<dependency> <groupId>io.bootique.swagger</groupId> <artifactId>bootique-swagger-ui</artifactId> </dependency>
To view the spec from the same app (e.g. the one added via
bootique-swagger-openapi as described above), add the
relative path of the model resource to the app configuration:
swaggerui: default: specPath: model/openapi.json
When you start the application, the console will be available at
If you are running behind a proxy, make sure you pass the correct
Host header with the
host[:port] of the proxy,
or the browser will not be able to discover your specification endpoint and/or won't be able to invoke it properly.
nginx proxy you might use the following config:
proxy_set_header Host $http_host;
To view a spec from another app, configure specification public URL like this:
swaggerui: default: specUrl: https://example.org/model/openapi.json