Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

build test deploy Maven Central


Integrates Swagger REST API documentation services with Bootique. Supports modern OpenAPI 3 specification. Contains the following modules:

  • 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.



Include bootique-bom:


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 @Path, @GET, etc. and Swagger annotations. To include one or more specification resources, add the following dependency:


And then configure the layout and the sources of the specs:

    # arbitrary name of a spec endpoint... Multiple specs at different URLs are supported

      # 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"
        - "com.example.api"
        - "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:

  1. "resourcePackages" / "resourceClasses": This provides the metadata collected from endpoint Java classes and annotations.
  2. "spec": This is a YAML or JSON file. Combined with "1", overriding any common properties.
  3. "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:

Web UI

Bootique integrates Swagger browser UI to be able to view and interact with the API specs:


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:

    specPath: model/openapi.json

When you start the application, the console will be available at /<appcontext>/swagger-ui. E.g. .

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: