juneau-bean-openapi-v3

The juneau-bean-openapi-v3 module provides Java beans for working with OpenAPI 3.0 documents and user interfaces.

Overview

This module contains predefined POJOs for:

• OpenAPI 3.0 document structure
• API documentation generation
• OpenAPI UI rendering
• Schema validation

OpenAPI Documents

The Juneau OpenAPI DTO beans are simply beans with fluent-style setters that allow you to quickly construct OpenAPI documents as Java objects. These objects can then be serialized to JSON using one of the existing JSON serializers, or to other languages such as XML or HTML using the other serializers.

The OpenApi3Builder class is a utility class with predefined static methods that allow you to easily construct DTO bean instances in a minimal amount of code.

The following is an example OpenAPI document:

{
    "openapi": "3.0.0",
    "info": {
        "title": "Pet Store API",
        "description": "This is a sample server Petstore server.",
        "version": "1.0.0",
        "contact": {
            "email": "apiteam@example.com"
        },
        "license": {
            "name": "Apache 2.0",
            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
        }
    },
    "servers": [
        {
            "url": "https://petstore.example.com/v2"
        }
    ],
    "tags": [
        {
            "name": "pet",
            "description": "Everything about your Pets"
        }
    ],
    "paths": {
        "/pet": {
            "post": {
                "tags": ["pet"],
                "summary": "Add a new pet to the store",
                "description": "",
                "operationId": "addPet",
                "requestBody": {
                    "description": "Pet object that needs to be added to the store",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "405": {
                        "description": "Invalid input"
                    }
                }
            }
        }
    }
}

This document can be generated by the following Java code:

static import org.apache.juneau.bean.openapi3.OpenApi3Builder.*;

OpenApi3 openApi = openApi3()
    .setOpenapi("3.0.0")
    .setInfo(
        info("Pet Store API", "1.0.0")
            .setDescription("This is a sample server Petstore server.")
            .setContact(
                contact().setEmail("apiteam@example.com")
            )
            .setLicense(
                license("Apache 2.0").setUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
            )
    )
    .setServers(
        server("https://petstore.example.com/v2")
    )
    .setTags(
        tag("pet").setDescription("Everything about your Pets")
    )
    .setPath("/pet", "post",
        operation()
            .setTags("pet")
            .setSummary("Add a new pet to the store")
            .setDescription("")
            .setOperationId("addPet")
            .setRequestBody(
                requestBody()
                    .setDescription("Pet object that needs to be added to the store")
                    .setRequired(true)
                    .setContent(
                        content("application/json")
                            .setSchema(schema().setType("object"))
                    )
            )
            .setResponse(405, response("Invalid input"))
    );

// Serialize using JSON serializer.
String openApiJson = Json.of(openApi);

// Or just use toString().
String openApiJson = openApi.toString();

OpenAPI UI

The OpenApi3UI class is a DTO bean class for generating OpenAPI user interfaces from OpenApi3 beans.

The class itself is nothing more than a POJO swap that swaps out OpenApi3 beans with Div elements.

public class OpenApi3UI extends ObjectSwap {

    @Override
    public MediaType[] forMediaTypes() {
        // Only use this swap when the Accept type is HTML.
        return new MediaType[] {MediaType.HTML};
    }

    @Override
    public Div swap(BeanSession beanSession, OpenApi3 openApi) throws Exception {
        // Generate HTML UI for OpenAPI document
        ...
    }
}

Usage in REST Services

The BasicRestServlet class shows how this swap is used in the REST interface to generate the OpenAPI UI:

@Rest(
    // Allow OPTIONS requests to be simulated using ?method=OPTIONS query parameter.
    allowedMethodParams="OPTIONS",
    ...
)
@BeanConfig(
    // POJO swaps to apply to all serializers/parsers.
    swaps={
        // Use the OpenApi3UI swap when rendering OpenAPI beans.
        OpenApi3UI.class
    }
)
public abstract class BasicRestServlet extends RestServlet implements BasicRestConfig {

    /**
     * [OPTIONS /*] - Show resource options.
     */
    @RestOp(
        method=OPTIONS,
        path="/*",
        summary="OpenAPI documentation",
        description="OpenAPI documentation for this resource."
    )
    @HtmlDocConfig(
        // Override the nav links for the OpenAPI page.
        navlinks={
            "back: servlet:/",
            "json: servlet:/?method=OPTIONS&Accept=text/json&plainText=true"
        },
        // Never show aside contents of page inherited from class.
        aside="NONE"
    )
    public OpenApi3 getOptions(RestRequest req) {
        // Localized OpenAPI for this resource is available through the RestRequest object.
        return req.getOpenApi3();
    }
}

Dependencies

• No external dependencies
• Part of the juneau-bean module group