Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Build Status Maven Central

bootique-swagger

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.

TODO: the examples below are based on the yet unreleased Bootique 2.0, and are only available as snapshots.

Usage

Prerequisites

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>

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:

<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:

  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:

<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 /<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:
  default:
    specUrl: https://example.org/model/openapi.json
You can’t perform that action at this time.