Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability. More at http://swagger.io

NOTE: This module depends on route spec, please read the route spec documentation to learn how to write powerful APIs.

• /swagger rout with SwaggerUI
• /swagger/swagger.json route
• /swagger/swagger.yml route

<dependency>
  <groupId>org.jooby</groupId>
  <artifactId>jooby-swagger</artifactId>
  <version>1.0.0.CR2</version>
</dependency>

{
  // define your API... via script or MVC:
  /**
   * Everything about your pets
   */
   use("/api/pets")
     /**
      * Get a pet by ID.
      * @param id Pet ID
      */
     .get("/:id", req -> {
       int id = req.param("id").intValue();
       DB db = req.require(DB.class);
       Pet pet = db.find(Pet.class, id);
       return pet;
     })
     ...;

  new Swagger().install(this);

}

Now the jooby:spec maven plugin:

<plugin>
  <groupId>org.jooby</groupId>
  <artifactId>jooby-maven-plugin</artifactId>
  <executions>
    <execution>
      <goals>
        <goal>spec</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Start your app and try:

• The Swagger-UI at /swagger
• The swagger.json at /swagger/swagger.json
• The swagger.yml at /swagger/swagger.yml

There are a few options available, let's see what they are:

The path option controls where to mount the Swagger routes:

{
  ...

  new Swagger("docs").install(this);

}

Produces: /docs for swagger-ui, /docs/swagger.json and /docs/swagger.yml. Default path is: /swagger.

The filter option controls what is exported to Swagger:

{
  ...

  new Swagger()
    .filter(route -> {
      return route.pattern().startsWith("/api");
    })
    .install(this);
}

Default filter keeps /api/* routes.

One ore more routes are grouped by a tag. The default tag provider produces pets for a route at /api/pets or /pets. You can specify your own tag provider via:

{
  new Swagger()
    .tag(route -> route.name())
    .install(this);
}

This option turn off the swagger-ui:

{
  ...

  new Swagger()
    .noUI()
    .install(this);
}

Check out the a live demo for Swagger.

Source code available at github

swagger {

  swagger: "2.0"

  info {

    title: ${application.name} API

    version: ${application.version}

  }

  basePath: ${application.path}

  consumes: ["application/json"]

  produces: ["application/json"]

  schemes: ["http"]

}