aarrsseni / bootique-swagger

Swagger integration with Bootique

bootique-swagger

This project integrates Swagger API documentation services into Bootique. It contains two modules:

• bootique-swagger: provides a REST service to dynamically generate JSON or YAML file, containing Swagger model. Generation is done from JAX-RS endpoints, annotated with Swagger documentation annotations. I.e. it appropriate for Swagger "code-first" flow.

• bootique-swagger-ui: provides swagger web UI that allows to inspect current app Swagger API model, as well as send test requests.

Usage

Prerequisites

Include bootique-bom:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.bootique.bom</groupId>
            <artifactId>bootique-bom</artifactId>
            <version>1.0.RC1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Next we need to provide a service that returns your app API spec (aka swagger.json). This service can then be used for manual inspection of the API structure, or more often accessed via the Swagger web UI, as described further down in this document. There are a few ways to serve swagger.json, depending on your workflow. Let's look at two of them - a static file and dynamically generated REST resource.

Static swagger.json

In this scenario, developer bundles swagger.json with her app and makes it acessible via bootique-jetty. There are a few ways to obtain this JSON file. Typically you'd write swagger.yaml by hand, and then convert it to swagger.json with swagger-codegen tool that has Maven plugin and CLI flavors. From here the steps are the same as with any static file that you want to expose via HTTP in a Bootique app. Here is one possible setup:

• Designate a "docroot" directory as a subdirectory of the project resources. E.g. src/main/resources/doctroot
• Configure bootique-jetty to include the "default" servlet rooted in this directory:

JettyModule.extend(binder).useDefaultServlet();
BQCoreModule.extend(binder).setProperty("bq.jetty.staticResourceBase", "classpath:docroot");

• Put swagger.json under docroot (i.e. at src/main/resources/doctroot/swagger.json).

Start the app and verify that the JOSN is accessible. E.g. at http://127.0.0.1:8080/swagger.json

swagger.json Auto-Generated from Java Annotations

In a typical "code-first" flow, you might manually annotate your Java REST resources with Swagger annotations instead of creating a static swagger.json. In this case include bootique-swagger dependency to dynamically generate the API model in runtime:

<dependency>
	<groupId>io.bootique.swagger</groupId>
	<artifactId>bootique-swagger</artifactId>
</dependency>

This results in two dynamic resources being added to your app, with URLs relative to your Jersey root URL:

• <your_rest_resources_root>/swagger.json. E.g. http://127.0.0.1:8080/swagger.json
• <your_rest_resources_root>/swagger.yaml. E.g. http://127.0.0.1:8080/swagger.yaml

Web UI (Since 1.0.RC1)

To include UI console inside the app:

<dependency>
	<groupId>io.bootique.swagger</groupId>
	<artifactId>bootique-swagger-ui</artifactId>
</dependency>

The UI will be accessible at your_rest_resources_root/swagger. E.g. http://127.0.0.1:8080/swagger/ . The static resources of swagger ui will be accessible at your_rest_resources_root/static. E.g. http://127.0.0.1:8080/static/swagger-ui.css .