juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/package.html - juneau - Git at Google

 <!DOCTYPE HTML>
 <!--
 /***************************************************************************************************************************
  * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
  *
  *  http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations under the License.
  *
  ***************************************************************************************************************************/
 -->
 <html>
 <head>
 	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 	<style type="text/css">
 		/* For viewing in Page Designer */
 		@IMPORT url("../../../../../../../javadoc.css");

 		/* For viewing in REST interface */
 		@IMPORT url("../htdocs/javadoc.css");
 		body {
 			margin: 20px;
 		}
 	</style>
 	<script>
 		/* Replace all @code and @link tags. */
 		window.onload = function() {
 			document.body.innerHTML = document.body.innerHTML.replace(/\{\@code ([^\}]+)\}/g, '<code>$1</code>');
 			document.body.innerHTML = document.body.innerHTML.replace(/\{\@link (([^\}]+)\.)?([^\.\}]+)\}/g, '<code>$3</code>');
 		}
 	</script>
 </head>
 <body>
 <p>Swagger Data Transfer Objects</p>
 <script>
 	function toggle(x) {
 		var div = x.nextSibling;
 		while (div != null && div.nodeType != 1)
 			div = div.nextSibling;
 		if (div != null) {
 			var d = div.style.display;
 			if (d == 'block' || d == '') {
 				div.style.display = 'none';
 				x.className += " closed";
 			} else {
 				div.style.display = 'block';
 				x.className = x.className.replace(/(?:^|\s)closed(?!\S)/g , '' );
 			}
 		}
 	}
 </script>
 <a id='TOC'></a><h5 class='toc'>Table of Contents</h5>
 <ol class='toc'>
 	<li><p><a class='doclink' href='#Overview'>Overview</a></p>
 	<ol>
 		<li><p><a class='doclink' href='#Serialize'>Generating Swagger Docs</a></p>
 		<li><p><a class='doclink' href='#Parse'>Parsing Swagger Docs</a></p>
 	</ol>
 </ol>


 <!-- ======================================================================================================== -->
 <a id="Overview"></a>
 <h2 class='topic' onclick='toggle(this)'>1 - Overview</h2>
 <div class='topic'>
 	<p>
 		Juneau supports generation and consumption of Swagger 2.0 documents and fragments through the use of DTOs
 		(Data Transfer Objects).
 		<br>It uses existing support for serializing and parsing POJOs to and from JSON to define these objects.
 	</p>

 	<!-- ======================================================================================================== -->
 	<a id="Serialize"></a>
 	<h3 class='topic' onclick='toggle(this)'>1.1 - Generating Swagger Docs</h3>
 	<div class='topic'>
 		<p>
 			The following is an example Swagger document from the <a href="http://petstore.swagger.io/">Swagger website</a>.
 		</p>
 		<p class='bcode'>
 	{
 		<jf>"swagger"</jf>: <js>"2.0"</js>,
 		<jf>"info"</jf>: {
 			<jf>"title"</jf>: <js>"Swagger Petstore"</js>,
 			<jf>"description"</jf>: <js>"This is a sample server Petstore server."</js>,
 			<jf>"version"</jf>: <js>"1.0.0"</js>,
 			<jf>"termsOfService"</jf>: <js>"http://swagger.io/terms/"</js>,
 			<jf>"contact"</jf>: {
 				<jf>"email"</jf>: <js>"apiteam@swagger.io"</js>
 			},
 			<jf>"license"</jf>: {
 				<jf>"name"</jf>: <js>"Apache 2.0"</js>,
 				<jf>"url"</jf>: <js>"http://www.apache.org/licenses/LICENSE-2.0.html"</js>
 			}
 		},
 		<jf>"host"</jf>: <js>"petstore.swagger.io"</js>,
 		<jf>"basePath"</jf>: <js>"/v2"</js>,
 		<jf>"tags"</jf>: [
 			{
 				<jf>"name"</jf>: <js>"pet"</js>,
 				<jf>"description"</jf>: <js>"Everything about your Pets"</js>,
 				<jf>"externalDocs"</jf>: {
 					<jf>"description"</jf>: <js>"Find out more"</js>,
 					<jf>"url"</jf>: <js>"http://swagger.io"</js>
 				}
 			}
 		],
 		<jf>"schemes"</jf>: [
 			<js>"http"</js>
 		],
 		<jf>"paths"</jf>: {
 			<jf>"/pet"</jf>: {
 				<jf>"post"</jf>: {
 					<jf>"tags"</jf>: [
 						<js>"pet"</js>
 					],
 					<jf>"summary"</jf>: <js>"Add a new pet to the store"</js>,
 					<jf>"description"</jf>: <js>""</js>,
 					<jf>"operationId"</jf>: <js>"addPet"</js>,
 					<jf>"consumes"</jf>: [
 						<js>"application/json"</js>,
 						<js>"text/xml"</js>
 					],
 					<jf>"produces"</jf>: [
 						<js>"application/json"</js>,
 						<js>"text/xml"</js>
 					],
 					<jf>"parameters"</jf>: [
 						{
 							<jf>"in"</jf>: <js>"body"</js>,
 							<jf>"name"</jf>: <js>"body"</js>,
 							<jf>"description"</jf>: <js>"Pet object that needs to be added to the store"</js>,
 							<jf>"required"</jf>: <jk>true</jk>
 						}
 					],
 					<jf>"responses"</jf>: {
 						<jf>"405"</jf>: {
 							<jf>"description"</jf>: <js>"Invalid input"</js>
 						}
 					}
 				}
 			}
 		},
 	}
 		</p>
 		<p>
 			This document can be generated by the following Java code:
 		</p>
 		<p class='bcode'>
 	<jk>static import</jk> org.apache.juneau.dto.swagger.SwaggerBuilder.*;

 	Swagger swagger = <jsm>swagger</jsm>()
 		.swagger(<js>"2.0"</js>)
 		.info(
 			<jsm>info</jsm>(<js>"Swagger Petstore"</js>, <js>"1.0.0"</js>)
 				.description(<js>"This is a sample server Petstore server."</js>)
 				.termsOfService(<js>"http://swagger.io/terms/"</js>)
 				.contact(
 					<jsm>contact</jsm>().email(<js>"apiteam@swagger.io"</js>)
 				)
 				.license(
 					<jsm>license</jsm>(<js>"Apache 2.0"</js>)
 						.url(<js>"http://www.apache.org/licenses/LICENSE-2.0.html"</js>)
 				)
 		)
 		.host(<js>"petstore.swagger.io"</js>)
 		.basePath(<js>"/v2"</js>)
 		.tags(
 			<jsm>tag</jsm>(<js>"pet"</js>).description(<js>"Everything about your Pets"</js>)
 				.externalDocs(
 					<jsm>externalDocumentation</jsm>(<js>"http://swagger.io"</js>, <js>"http://swagger.io"</js>)
 				)
 		)
 		.schemes(<js>"http"</js>)
 		.path(<js>"/pet"</js>, <js>"post"</js>,
 			<jsm>operation</jsm>()
 				.tags(<js>"pet"</js>)
 				.summary(<js>"Add a new pet to the store"</js>)
 				.description(<js>""</js>)
 				.operationId(<js>"addPet"</js>)
 				.consumes(MediaType.<jsf>JSON</jsf>, MediaType.<jsf>XML</jsf>)
 				.produces(MediaType.<jsf>JSON</jsf>, MediaType.<jsf>XML</jsf>)
 				.parameters(
 					<jsm>parameterInfo</jsm>(<js>"body"</js>, <js>"body"</js>)
 						.description(<js>"Pet object that needs to be added to the store"</js>)
 						.required(<jk>true</jk>)
 				)
 				.response(405, <jsm>responseInfo</jsm>(<js>"Invalid input"</js>))
 		);

 	String swaggerJson = JsonSerializer.<jsf>DEFAULT_READABLE</jsf>.serialize(swagger);
 		</p>
 	</div>

 	<!-- ======================================================================================================== -->
 	<a id="Parse"></a>
 	<h3 class='topic' onclick='toggle(this)'>1.2 - Parsing Swagger Docs</h3>
 	<div class='topic'>
 		<p>
 			Swagger docs can be parsed back into Swagger beans using the following code:
 		</p>
 		<p class='bcode'>
 	Swagger swagger = JsonParser.<jsf>DEFAULT</jsf>.parse(swaggerJson, Swagger.<jk>class</jk>);
 		</p>
 	</div>

 </div>

 </body>
 </html>
	<!DOCTYPE HTML>
	<!--
	/***************************************************************************************************************************
	* Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
	* to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
	* with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
	* specific language governing permissions and limitations under the License.
	*
	***************************************************************************************************************************/
	-->
	<html>
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<style type="text/css">
	/* For viewing in Page Designer */
	@IMPORT url("../../../../../../../javadoc.css");

	/* For viewing in REST interface */
	@IMPORT url("../htdocs/javadoc.css");
	body {
	margin: 20px;
	}
	</style>
	<script>
	/* Replace all @code and @link tags. */
	window.onload = function() {
	document.body.innerHTML = document.body.innerHTML.replace(/\{\@code ([^\}]+)\}/g, '<code>$1</code>');
	document.body.innerHTML = document.body.innerHTML.replace(/\{\@link (([^\}]+)\.)?([^\.\}]+)\}/g, '<code>$3</code>');
	}
	</script>
	</head>
	<body>
	<p>Swagger Data Transfer Objects</p>
	<script>
	function toggle(x) {
	var div = x.nextSibling;
	while (div != null && div.nodeType != 1)
	div = div.nextSibling;
	if (div != null) {
	var d = div.style.display;
	if (d == 'block' \|\| d == '') {
	div.style.display = 'none';
	x.className += " closed";
	} else {
	div.style.display = 'block';
	x.className = x.className.replace(/(?:^\|\s)closed(?!\S)/g , '' );
	}
	}
	}
	</script>
	<a id='TOC'></a><h5 class='toc'>Table of Contents</h5>
	<ol class='toc'>
	<li><p><a class='doclink' href='#Overview'>Overview</a></p>
	<ol>
	<li><p><a class='doclink' href='#Serialize'>Generating Swagger Docs</a></p>
	<li><p><a class='doclink' href='#Parse'>Parsing Swagger Docs</a></p>
	</ol>
	</ol>


	<!-- ======================================================================================================== -->
	<a id="Overview"></a>
	<h2 class='topic' onclick='toggle(this)'>1 - Overview</h2>
	<div class='topic'>
	<p>
	Juneau supports generation and consumption of Swagger 2.0 documents and fragments through the use of DTOs
	(Data Transfer Objects).
	<br>It uses existing support for serializing and parsing POJOs to and from JSON to define these objects.
	</p>

	<!-- ======================================================================================================== -->
	<a id="Serialize"></a>
	<h3 class='topic' onclick='toggle(this)'>1.1 - Generating Swagger Docs</h3>
	<div class='topic'>
	<p>
	The following is an example Swagger document from the <a href="http://petstore.swagger.io/">Swagger website</a>.
	</p>
	<p class='bcode'>
	{
	<jf>"swagger"</jf>: <js>"2.0"</js>,
	<jf>"info"</jf>: {
	<jf>"title"</jf>: <js>"Swagger Petstore"</js>,
	<jf>"description"</jf>: <js>"This is a sample server Petstore server."</js>,
	<jf>"version"</jf>: <js>"1.0.0"</js>,
	<jf>"termsOfService"</jf>: <js>"http://swagger.io/terms/"</js>,
	<jf>"contact"</jf>: {
	<jf>"email"</jf>: <js>"apiteam@swagger.io"</js>
	},
	<jf>"license"</jf>: {
	<jf>"name"</jf>: <js>"Apache 2.0"</js>,
	<jf>"url"</jf>: <js>"http://www.apache.org/licenses/LICENSE-2.0.html"</js>
	}
	},
	<jf>"host"</jf>: <js>"petstore.swagger.io"</js>,
	<jf>"basePath"</jf>: <js>"/v2"</js>,
	<jf>"tags"</jf>: [
	{
	<jf>"name"</jf>: <js>"pet"</js>,
	<jf>"description"</jf>: <js>"Everything about your Pets"</js>,
	<jf>"externalDocs"</jf>: {
	<jf>"description"</jf>: <js>"Find out more"</js>,
	<jf>"url"</jf>: <js>"http://swagger.io"</js>
	}
	}
	],
	<jf>"schemes"</jf>: [
	<js>"http"</js>
	],
	<jf>"paths"</jf>: {
	<jf>"/pet"</jf>: {
	<jf>"post"</jf>: {
	<jf>"tags"</jf>: [
	<js>"pet"</js>
	],
	<jf>"summary"</jf>: <js>"Add a new pet to the store"</js>,
	<jf>"description"</jf>: <js>""</js>,
	<jf>"operationId"</jf>: <js>"addPet"</js>,
	<jf>"consumes"</jf>: [
	<js>"application/json"</js>,
	<js>"text/xml"</js>
	],
	<jf>"produces"</jf>: [
	<js>"application/json"</js>,
	<js>"text/xml"</js>
	],
	<jf>"parameters"</jf>: [
	{
	<jf>"in"</jf>: <js>"body"</js>,
	<jf>"name"</jf>: <js>"body"</js>,
	<jf>"description"</jf>: <js>"Pet object that needs to be added to the store"</js>,
	<jf>"required"</jf>: <jk>true</jk>
	}
	],
	<jf>"responses"</jf>: {
	<jf>"405"</jf>: {
	<jf>"description"</jf>: <js>"Invalid input"</js>
	}
	}
	}
	}
	},
	}
	</p>
	<p>
	This document can be generated by the following Java code:
	</p>
	<p class='bcode'>
	<jk>static import</jk> org.apache.juneau.dto.swagger.SwaggerBuilder.*;

	Swagger swagger = <jsm>swagger</jsm>()
	.swagger(<js>"2.0"</js>)
	.info(
	<jsm>info</jsm>(<js>"Swagger Petstore"</js>, <js>"1.0.0"</js>)
	.description(<js>"This is a sample server Petstore server."</js>)
	.termsOfService(<js>"http://swagger.io/terms/"</js>)
	.contact(
	<jsm>contact</jsm>().email(<js>"apiteam@swagger.io"</js>)
	)
	.license(
	<jsm>license</jsm>(<js>"Apache 2.0"</js>)
	.url(<js>"http://www.apache.org/licenses/LICENSE-2.0.html"</js>)
	)
	)
	.host(<js>"petstore.swagger.io"</js>)
	.basePath(<js>"/v2"</js>)
	.tags(
	<jsm>tag</jsm>(<js>"pet"</js>).description(<js>"Everything about your Pets"</js>)
	.externalDocs(
	<jsm>externalDocumentation</jsm>(<js>"http://swagger.io"</js>, <js>"http://swagger.io"</js>)
	)
	)
	.schemes(<js>"http"</js>)
	.path(<js>"/pet"</js>, <js>"post"</js>,
	<jsm>operation</jsm>()
	.tags(<js>"pet"</js>)
	.summary(<js>"Add a new pet to the store"</js>)
	.description(<js>""</js>)
	.operationId(<js>"addPet"</js>)
	.consumes(MediaType.<jsf>JSON</jsf>, MediaType.<jsf>XML</jsf>)
	.produces(MediaType.<jsf>JSON</jsf>, MediaType.<jsf>XML</jsf>)
	.parameters(
	<jsm>parameterInfo</jsm>(<js>"body"</js>, <js>"body"</js>)
	.description(<js>"Pet object that needs to be added to the store"</js>)
	.required(<jk>true</jk>)
	)
	.response(405, <jsm>responseInfo</jsm>(<js>"Invalid input"</js>))
	);

	String swaggerJson = JsonSerializer.<jsf>DEFAULT_READABLE</jsf>.serialize(swagger);
	</p>
	</div>

	<!-- ======================================================================================================== -->
	<a id="Parse"></a>
	<h3 class='topic' onclick='toggle(this)'>1.2 - Parsing Swagger Docs</h3>
	<div class='topic'>
	<p>
	Swagger docs can be parsed back into Swagger beans using the following code:
	</p>
	<p class='bcode'>
	Swagger swagger = JsonParser.<jsf>DEFAULT</jsf>.parse(swaggerJson, Swagger.<jk>class</jk>);
	</p>
	</div>

	</div>

	</body>
	</html>