Juneau supports generation and consumption of Swagger 2.0 documents and fragments through the use of DTOs
(Data Transfer Objects).
It uses existing support for serializing and parsing POJOs to and from JSON to define these objects.
The following is an example Swagger document from the Swagger website.
{
"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",
"description": "",
"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"
}
}
}
}
},
}
This document can be generated by the following Java code:
static import org.apache.juneau.dto.swagger.SwaggerBuilder.*;
Swagger swagger = swagger()
.swagger("2.0")
.info(
info("Swagger Petstore", "1.0.0")
.description("This is a sample server Petstore server.")
.termsOfService("http://swagger.io/terms/")
.contact(
contact().email("apiteam@swagger.io")
)
.license(
license("Apache 2.0")
.url("http://www.apache.org/licenses/LICENSE-2.0.html")
)
)
.host("petstore.swagger.io")
.basePath("/v2")
.tags(
tag("pet").description("Everything about your Pets")
.externalDocs(
externalDocumentation("http://swagger.io", "http://swagger.io")
)
)
.schemes("http")
.path("/pet", "post",
operation()
.tags("pet")
.summary("Add a new pet to the store")
.description("")
.operationId("addPet")
.consumes(MediaType.JSON, MediaType.XML)
.produces(MediaType.JSON, MediaType.XML)
.parameters(
parameterInfo("body", "body")
.description("Pet object that needs to be added to the store")
.required(true)
)
.response(405, responseInfo("Invalid input"))
);
String swaggerJson = JsonSerializer.DEFAULT_READABLE.serialize(swagger);
Swagger docs can be parsed back into Swagger beans using the following code:
Swagger swagger = JsonParser.DEFAULT.parse(swaggerJson, Swagger.class);