GeezerVison

/**
* My Library.
* @version 5.4.1
* @tag Books. All about books.
* @server.url https://books.api.com
* @server.description Production
* @x-logo https://my.api.com/logo.png
*/
public class App extends Jooby {
  {
    install(new OpenAPIModule());

    /*
     * Books operations.
     * @tag Books
    */
    path("/api/books", () -> {
        /*
         * Query and filter books.
         *
         * @param query Book filter.
         * @return List of matching books.
         * @operationId query
         */
        get("/", ctx -> {
         var query = ctx.query(BookQuery.class);
        });
        /*
         * Find a book by ISBN.
         * @param isbn ISBN code.
         * @return A book.
         * @throws BookNotFoundException When a book doesn't exist. <code>404</code>
         * @operationId bookByIsbn
         */
        get("/{isbn}", ctx -> {
         var query = ctx.query(BookQuery.class);
        });
    });

  }
}

/**
 * Book query.
 *
 * @type Book type.
 * @aga Book age.
 */
public record BookQuery(BookType type, int age) {}

/**
 * Books can be broadly categorized into fiction and non-fiction
 */
public enum BookType {
  /**
  * Fiction includes genres like fantasy, science fiction, romance, and mystery.
  */
  Fiction,
  /**
  * Non-fiction encompasses genres like history, biography, and self-help.
  */
  NonFiction
}

/**
* My Library.
* @version 5.4.1
* @tag Books. All about books.
* @server.url https://books.api.com
* @server.description Production
* @x-logo https://my.api.com/logo.png
*/
public class App extends Jooby {
  {
    mvc(new Books_());
    install(new OpenAPIModule());
  }
}
/**
 * Books operations.
 * @tag Books
 */
@Path("/api/books")
public class Books {
  /**
   * Query and filter books.
    *
   * @param query Book filter.
   * @return List of matching books.
   */
  public List<Book> query(@QueryParam BookQuery query) {
     ....
  }
  /**
   * Find a book by ISBN.
   *
   * @param isbn ISBN code.
   * @return A book.
   * @throws BookNotFoundException When a book doesn't exist. <code>404</code>
   */
  public Book bookByIsbn(@PathParam String isbn) {

  }
}

/**
 * Book query.
 *
 * @type Book type.
 * @aga Book age.
 */
public record BookQuery(BookType type, int age) {}

/**
 * Books can be broadly categorized into fiction and non-fiction
 */
public enum BookType {
  /**
  * Fiction includes genres like fantasy, science fiction, romance, and mystery.
  */
  Fiction,
  /**
  * Non-fiction encompasses genres like history, biography, and self-help.
  */
  NonFiction
}

openapi: 3.0.1
info:
  title: My Super API
  description: |
    Nunc commodo ipsum vitae dignissim congue. Quisque convallis malesuada tortor, non
    lacinia quam malesuada id. Curabitur nisi mi, lobortis non tempus vel, vestibulum et neque.

    ...
  version: "1.0"
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  paths:
    /api/pets:
      get:
        operationId: listPets
        description: List and sort pets.
        parameters:
          name: page
            descripton: Page number.

@OpenAPIDefinition(
    info = @Info(
        title = "Title",
        description = "description",
        termsOfService = "Terms",
        contact = @Contact(
            name = "Jooby",
            url = "https://jooby.io",
            email = "[email protected]"
        ),
        license = @License(
            name = "Apache",
            url = "https://jooby.io/LICENSE"
        ),
        version = "10"
    ),
    tags = @Tag(name = "mytag")
)
class App extends Jooby {
  {
    // All routes now have the default tag: `Pets`
  }
}

@OpenAPIDefinition(
    info = Info(
        title = "Title",
        description = "description",
        termsOfService = "Terms",
        contact = Contact(
            name = "Jooby",
            url = "https://jooby.io",
            email = "[email protected]"
        ),
        license = License(
            name = "Apache",
            url = "https://jooby.io/LICENSE"
        ),
        version = "10"
    ),
    tags = [Tag(name = "mytag")]
)
class App: Kooby({
})

@Tag(name = "Pets", description = "Pet operations")
class App extends Jooby {
  {
    // All routes now have the default tag: `Pets`
  }
}

@Tag(name = "Pets", description = "Pet operations")
class App: Kooby({
    // All routes now have the default tag: `Pets`
})

@Tag(name = "Pets", description = "Pet operations")
@Path("/pets")
class Pets {
  // All web method now have the default tag: `Pets`
}

@Tag(name = "Pets", description = "Pet operations")
@Path("/pets")
class Pets {
  // All web method now have the default tag: `Pets`
}

@Tag(name = "Pets", description = "Pet operations")
public List<Pet> list(Context ctx) {
  ...
}

@Tag(name = "Pets", description = "Pet operations")
fun list(ctx: Context): List<Pet> {
  ...
}

@ApiResponse(description = "This is the default response")

@ApiResponse(responseCode = "201", description = "This is the default response")

@ApiResponses({
  @ApiResponse(description = "This is the default response"),
  @ApiResponse(responseCode = "500"),
  @ApiResponse(responseCode = "400"),
  @ApiResponse(responseCode = "404")
})

1) create your template: doc/library.adoc

2) add to build process

3) The output directory will have two files: - library.adoc (final asciidoctor file) - library.html (asciidoctor output)

The Jooby OpenAPI Template Engine is a tool designed to generate comprehensive AsciiDoc (.adoc) documentation directly from your Jooby application’s OpenAPI model.

It uses pebble as a pre-processor to automate redundant tasks. Instead of manually writing repetitive documentation for every endpoint, you write a single template that pulls live data from your code (routes, schemas, javadoc).

Pebble Syntax Primer

Data generation follows a flexible pipeline architecture. You start with a source and can optionally transform it before rendering.

1. Source: Finds an object in the OpenAPI model (e.g., a route or schema).

2. Mutator (Optional): Transforms or filters the data (e.g., extracting just the body, or filtering parameters).

3. Display: Renders the final output (e.g., as JSON, a Table, or a cURL command).

Examples

These functions are your entry points to locate objects within the OpenAPI definition.

Mutators modify the data stream. They are optional but powerful for drilling down into specific parts of an object.

The final step in the chain. These filters determine how the data is written to the AsciiDoc file.

A. Documenting a Route (The "Standard" Block)

// 1. Define the route
{% set route = GET("/library/books/{isbn}") %}

=== {{ route.summary }}

{{ route.description }}

// 2. Render Path Params
.Path Parameters
{{ route | parameters(path) | table }}

// 3. Render Query Params
.Query Parameters
{{ route | parameters(query) | table }}

// 4. Render Response + example
.Response
{{ route | response | body | example | json }}

// 5. Render Response and Override Status Code
.Created(201) Response
{{ route | response(201) | http }}

// 6. Render Response 400
.Bad Request Response
{{ route | response(400) | http }}

{{ route | response(400) | json }}

B. The "Try It" Button (cURL)

{{ POST("/items") | curl }}

{{ POST("/items") | curl("-i", "-H", "'Accept: application/xml'") }}

{{ POST("/items") | curl(language="bash") }}

C. Simulating specific scenarios

// Scenario: Searching for Sci-Fi books on page 2
GET {{ GET("/search") | path(q="Sci-Fi", page=2) }}

D. Simplifying Complex Objects

// Full Graph (Huge JSON)
{{ schema("Book") | example | json }}

// Summary (Flat JSON)
{{ schema("Book") | truncate | example | json }}

E. Error Response Reference

.404 Not Found
{{ error(404) | json }}

// Define the custom error shape once
{%- set error = {
    "code": "{{code}}",
    "message": "{{message}}",
    "reason": "{{reason}}",
    "timestamp": "2025-01-01T12:00:00Z",
    "support": "[email protected]"
} -%}

// Now generate the error. It will use the map above.
.400 Bad Request
{{ error(400) | json }}

{
  "code": 400,
  "message": "Bad Request",
  "reason": "Bad Request",
  "timestamp": "2025-01-01T12:00:00Z",
  "support": "[email protected]"
}

F. Dynamic Tag Loop

{% for tag in tags %}
== {{ tag.name }}
  {% for route in tag.routes %}
  === {{ route.summary }}
  {{ route.method }} {{ route.path }}
  {% endfor %}
{% endfor %}

G. Reusable Macros (DRY)

{# 1. Define the Macro at the top of your file #}
{% macro deprecationWarning(since) %}
[WARNING]
====
This endpoint is deprecated since version {{ since }}.
Please use the newer version instead.
====
{% endmacro %}

{# 2. Use it inside your route loop #}
{% if route.deprecated %}
    {{ deprecationWarning("v2.1") }}
{% endif %}

H. Security & Permissions

{% if route.security %}
.Required Permissions
[cols="1,3"]
|===
|Type | Scopes

{# Iterate through security schemes #}
{% for scheme in route.security %}
    {% for req in scheme %}
| *{{ loop.key }}* | {{ req | join(", ") }}
    {% endfor %}
{% endfor %}
|===
{% endif %}

I. Linking to Schema Definitions

{# 1. Create Anchors in your Schema Loop #}
{% for s in schemas %}
[id="{{ s.name }}"]
== {{ s.name }}
{{ s | table }}
{% endfor %}

{# 2. Link to them in your Route Loop #}
.Response Type
Returns a {{ route | response | link }} object.

<dependency>
  <groupId>io.jooby</groupId>
  <artifactId>jooby-swagger-ui</artifactId>
  <version>4.6.0</version>
</dependency>

implementation 'io.jooby:jooby-swagger-ui:4.6.0'

<dependency>
  <groupId>io.jooby</groupId>
  <artifactId>jooby-redoc</artifactId>
  <version>4.6.0</version>
</dependency>

implementation 'io.jooby:jooby-redoc:4.6.0'