org.apache.juneau.dto.swagger.package.html Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of juneau-all
Apache Juneau UberJar
There is a newer version: 9.0.1




	
	
	


Swagger Data Transfer Objects

Table of Contents

	Overview
	
		Generating Swagger Docs
		
Parsing Swagger Docs
	





1 - Overview

	
		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. 
	
	
	
	
	1.1 - Generating Swagger Docs
	
		
			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": "[email protected]"
			},
			"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("[email protected]")
				)
				.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);
		
		
	
	
	
	1.2 - Parsing Swagger Docs
	
		
			Swagger docs can be parsed back into Swagger beans using the following code:
		
		
	Swagger swagger = JsonParser.DEFAULT.parse(swaggerJson, Swagger.class);