Integrates Swagger REST API documentation services with Bootique. Supports modern OpenAPI 3 specification, as well as the legacy Swagger 2 spec. Contains the following modules:
-
bootique-swagger-openapi
: 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
: a legacy service generating Swagger 2 API descriptors. -
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.
Include bootique-bom
:
<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>
Swagger can generate application API specification dynamically based purely on the endpoint class/method signatures and JAX-RS
annotations (such as @Path
, @GET
, etc.). And then you would "enrich" the basic specification via the following mechanisms:
To expose the final specification as JSON and YAML resources, add the following dependency:
<dependency>
<groupId>io.bootique.swagger</groupId>
<artifactId>bootique-swagger-openapi</artifactId>
</dependency>
Now, when you run the app, you should be able to access the specs at the URLs similar to these:
A more complex workflow is when you have one or more API specifications, generate Java code from them (models, API endpoints), and then need to combine them together and/or extend them with extra app-specific fragments. So essentially going from specification(s) to code and then back to a single specification ("Spec-Code-Spec").
Everything described in the "Code-First" section above is fully applicable to the last step of this workflow
(i.e. going from code to spec), but the first step (going from spec(s) to code) is not handled by
bootique-swagger-openapi
and requires a third-party code generator.
There are various code generators available (such as
openapi-generator), but as of this writing (March 2020), most do not
support OpenAPI-compatible Swagger annotations (io.swagger.core.v3:swagger-annotations
package). The only tool that
we found to support it is unsurprisingly coming from Swagger itself. It is
swagger-codegen, v.3.0.x. You can download
the jar file
from Maven Central, and run the generator like this:
java -jar swagger-codegen-cli-3.0.18.jar generate -l jaxrs-jersey \
-o myproject
-i mymodel.yaml
There are also options to integrate this in Maven.
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:
specPath: openapi.json
When you start the application, the console will be available at /<appcontext>/swagger-ui
. E.g.
http://127.0.0.1:8080/swagger-ui/ .
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.
E.g. for 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:
specUrl: https://example.org/path/to/openapi.json