Overview

This plugin integrates Swagger UI to your Spincast REST API application.

It creates an endpoint that displays your OpenAPI documentation in an easy to browse and use HTML interface. You can use Swagger UI to display a hand-written specifications file or specifications generated by the Spincast OpenAPI bottom up plugin.

Usage

Simply by installing this plugin, a route will be added to your router and will serve OpenAPI specifications. You change the default configurations to tweak the path of this endpoint and to make it use the specifications of your API.

Install the plugin, configure it, starts your application and hit "/swagger-ui" (the default path) in your browser!

Configurations

In your Guice module, you need to bind a custom implementation of SpincastSwaggerUiConfig in order to configure this plugin. Your implementation can extend SpincastSwaggerUiConfigDefault as a base class.

Here are the available configurations you can override:

  • String getSwaggerUiPath()

    The path used to serve Swagger UI.

    The default is "/swagger-ui".

  • String getOpenApiSpecificationsUrl()

    The path (or absolute URL) to the OpenAPI specifications to be served. If you are using the Spincast OpenAPI bottom up plugin to generate your specifications, it would be this path.

    The default is to point to the example specifications provided by Swagger UI: "https://petstore.swagger.io/v2/swagger.json".

  • boolean showTopBar()

    Should the Swagger UI's top bar be displayed? This bar allows visitors to select a different specifications file than the one you selected.

    The default is false, the top bar is hidden.

Installation

1. Add this Maven artifact to your project:

<dependency>
    <groupId>org.spincast</groupId>
    <artifactId>spincast-plugins-swagger-ui</artifactId>
    <version>2.2.0</version>
</dependency>

2. Add an instance of the SpincastSwaggerUiPlugin plugin to your Spincast Bootstrapper:


Spincast.configure()
        .plugin(new SpincastSwaggerUiPlugin())
        // ...