juneau-bean-swagger-v2

The juneau-bean-swagger-v2 module provides Java beans for working with Swagger 2.0 documents and user interfaces.

Overview

This module contains predefined POJOs for:

• Swagger 2.0 document structure
• API documentation generation
• Swagger UI rendering

The beans are simply POJOs with fluent-style setX(...) setters, so they can be serialized to JSON using any of the Juneau JSON serializers, or to other languages such as XML or HTML using the other serializers.

Swagger Documents

The SwaggerBuilder class is a utility class with predefined static factory methods that let you construct Swagger DTO beans in a minimal amount of code. Typically you static-import it and call the factory methods directly.

import static org.apache.juneau.bean.swagger.SwaggerBuilder.*;
import java.net.URI;

Swagger swagger = swagger()
    .setSwagger("2.0")
    .setInfo(
        info("Swagger Petstore", "1.0.0")
            .setDescription("This is a sample server Petstore server.")
            .setTermsOfService("http://swagger.io/terms/")
            .setContact(
                contact().setEmail("apiteam@swagger.io")
            )
            .setLicense(
                license("Apache 2.0", URI.create("http://www.apache.org/licenses/LICENSE-2.0.html"))
            )
    )
    .setHost("petstore.swagger.io")
    .setBasePath("/v2")
    .setTags(
        tag("pet").setDescription("Everything about your Pets")
            .setExternalDocs(
                externalDocumentation("http://swagger.io", "Find out more")
            )
    )
    .addSchemes("http")
    .addOperation("/pet", "post",
        operation()
            .setTags("pet")
            .setSummary("Add a new pet to the store")
            .setDescription("")
            .setOperationId("addPet")
            .addConsumes(MediaType.JSON, MediaType.XML)
            .addProduces(MediaType.JSON, MediaType.XML)
            .setParameters(
                parameterInfo("body", "body")
                    .setDescription("Pet object that needs to be added to the store")
                    .setRequired(true)
            )
            .addResponse("405", responseInfo("Invalid input"))
    );

// Serialize using the JSON serializer.
String swaggerJson = Json.of(swagger);

// Or just use toString() / asJson().
swaggerJson = swagger.asJson();

Produces:

{
    "swagger": "2.0",
    "info": {
        "title": "Swagger Petstore",
        "description": "This is a sample server Petstore server.",
        "version": "1.0.0",
        "termsOfService": "http://swagger.io/terms/",
        "contact": {
            "email": "apiteam@swagger.io"
        },
        "license": {
            "name": "Apache 2.0",
            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
        }
    },
    "host": "petstore.swagger.io",
    "basePath": "/v2",
    "tags": [
        {
            "name": "pet",
            "description": "Everything about your Pets",
            "externalDocs": {
                "description": "Find out more",
                "url": "http://swagger.io"
            }
        }
    ],
    "schemes": ["http"],
    "paths": {
        "/pet": {
            "post": {
                "tags": ["pet"],
                "summary": "Add a new pet to the store",
                "operationId": "addPet",
                "consumes": ["application/json", "text/xml"],
                "produces": ["application/json", "text/xml"],
                "parameters": [
                    {
                        "in": "body",
                        "name": "body",
                        "description": "Pet object that needs to be added to the store",
                        "required": true
                    }
                ],
                "responses": {
                    "405": {
                        "description": "Invalid input"
                    }
                }
            }
        }
    }
}

Because these are standard Juneau beans, a Swagger document parses back from any supported format:

import org.apache.juneau.marshall.json.*;

Swagger back = JsonParser.DEFAULT.read(swaggerJson, Swagger.class);

SwaggerUI

The SwaggerUI class is a DTO bean class for generating Swagger user interfaces from Swagger beans.

The class itself is nothing more than a POJO swap (ObjectSwap<Swagger,Div>) that swaps out Swagger beans with Div elements when the requested media type is HTML.

public class SwaggerUI extends ObjectSwap<Swagger,Div> {

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

    @Override
    public Div swap(MarshallingSession session, Swagger swagger) throws Exception {
        // Generate an HTML UI for the Swagger document.
        ...
    }
}

When rendered against a REST resource's generated Swagger, it produces a browsable Swagger UI. Given this auto-generated Swagger JSON:

SwaggerUI renders it as a Swagger user interface when the request asks for HTML:

Bean Classes

Class	Purpose
Swagger	Top-level Swagger 2.0 document.
Info	API metadata (title, version, description, contact, license).
Contact / License	Contact and license sub-objects of Info.
Tag	Tag descriptor with optional external docs.
Operation	A single API operation on a path/method.
ParameterInfo	Operation parameter descriptor.
ResponseInfo	Operation response descriptor.
SchemaInfo / Items	Schema and array-item descriptors.
HeaderInfo	Response header descriptor.
SecurityScheme	Security-definition descriptor.
ExternalDocumentation	External-documentation reference.
Xml	XML serialization hints for a schema.
SwaggerUI	POJO swap that renders a Swagger document as an HTML UI.

Dependencies

• Runtime: juneau-marshall (and juneau-bean-html5 for SwaggerUI)
• External: None
• Part of: juneau-bean module group

Resources

• Swagger 2.0 Specification