RESTful API Modeling Language (RAML) makes it easy to manage the whole API lifecycle from design to sharing. It's concise - you only write what you need to define - and reusable. It is machine readable API design that is actually human friendly. More at http://raml.org

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

• /raml route with api-console
• /raml/api.raml route

<dependency>
 <groupId>org.jooby</groupId>
 <artifactId>jooby-raml</artifactId>
 <version>1.0.0</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 = require(DB.class);
       Pet pet = db.find(Pet.class, id);
       return pet;
     })
     ...;

  new Raml().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 api-console at /raml
• The .raml file at /raml/api.raml

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

The path option controls where to mount the RAML routes:

{
  ...

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

}

Produces: /docs for api-console and /docs/api.raml. Default path is: /raml.

The filter option controls what is exported to RAML:

{
  ...

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

Default filter keeps /api/* routes.

This option turn off the api-console:

{
  ...

  new Raml()
    .noConsole()
    .install(this);
}

Set the ui-theme for api-console. Available options are light and dark. Default is: light.

{
  ...

  new Raml()
    .theme("dark")
    .install(this);
}

Shows/hide the client generator button from api-console.

Expand/collapse the try it panel from api-console.

Check out the a live demo for RAML.

Source code available at github

raml {

  title: ${application.name} API

  version: ${application.version}

  baseUri: "http://"${application.host}":"${application.port}${application.path}

  mediaType: "application/json"

  protocols: [HTTP]

}