juneau-doc/docs/Topics/06.juneau-rest-server/29.Swagger/02.BasicSwaggerInfo.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.
 ***************************************************************************************************************************/
 -->

Basic Swagger Info

<p>
	Let's look at the various parts of the <c>Petstore</c> application Swagger UI to see how they are defined.
</p>
<p>
	The top part of the page shows general information about the REST interface:
</p>
<img class='bordered w900' src='doc-files/juneau-rest-server.Swagger.3.png'>
<p>
	The information is pulled from the {@link oajr.annotation.Rest#swagger() @Rest(swagger)} annotation.
</p>
<h5 class='figure'>org.apache.juneau.examples.rest.petstore.PetStoreResource</h5>
<p class='bpcode w800'>
	<ja>@Rest</ja>(
		path=<js>"/petstore"</js>,
		title=<js>"Petstore application"</js>,
		...
		swagger=@ResourceSwagger(<js>"$F{PetStoreResource.json}"</js>),
		...
	)
	<jk>public class</jk> PetStoreResource <jk>extends</jk> BasicRestServletJena {...}
</p>
<p>
	In this particular case, the Swagger is pulled in from a localized Swagger JSON file located in the 
	<c>org.apache.juneau.examples.rest.petstore</c> package using the {@link oajr.vars.FileVar $F} variable.
</p>
<h5 class='figure'>PetStoreResource.json</h5>
<p class='bpcode w800'>
	{
		<jok>"swagger"</jok>: <jov>"2.0"</jov>,
		<jok>"info"</jok>: {
			<jok>"version"</jok>: <jov>"1.0.0"</jov>,
			<jok>"title"</jok>: <jov>"Swagger Petstore"</jov>,
			<jok>"termsOfService"</jok>: <jov>"You are on your own."</jov>,
			<jok>"contact"</jok>: {
				<jok>"name"</jok>: <jov>"Juneau Development Team"</jov>,
				<jok>"email"</jok>: <jov>"dev@juneau.apache.org"</jov>,
				<jok>"url"</jok>: <jov>"http://juneau.apache.org"</jov>
			},
			<jok>"license"</jok>: {
				<jok>"name"</jok>: <jov>"Apache 2.0"</jov>,
				<jok>"url"</jok>: <jov>"http://www.apache.org/licenses/LICENSE-2.0.html"</jov>
			}
		},
		<jok>"externalDocs"</jok>: {
			<jok>"description"</jok>: <jov>"Find out more about Juneau"</jov>,
			<jok>"url"</jok>: <jov>"http://juneau.apache.org"</jov>
		},
		...
	}
</p>
<p>
	Note that the {@link oajr.vars.FileVar $F} variable allows for request-locale-sensitive name matching so that you can provide
	localized Swagger information.
</p>
<p>
	The {@link oajr.vars.FileVar $F} variable simply expands to a string to fill the {@link oajr.annotation.ResourceSwagger#value() @ResourceSwagger(value)}
	annotation.  
	You could equivalently embed JSON directly into your annotation like so:
</p>
<p class='bpcode w800'>
	<ja>@Rest</ja>(
		path=<js>"/petstore"</js>,
		title=<js>"Petstore application"</js>,
		...
		swagger=<ja>@ResourceSwagger</ja>(
			<jc>// Raw Simplified JSON.</jc>
			<jc>// Values are concatenated.
			<js>"{"</js>,
				<js>"swagger: '2.0',"</js>,
				<js>"version: '1.0.0',"</js>,
				...
			<js>"}"</js>
		),
		...
	)
	<jk>public class</jk> PetStoreResource <jk>extends</jk> BasicRestServletJena {...}
</p>
<p>
	However, a more typical (and less error-prone) scenario is to define all of your Swagger as annotations:
</p>
<p class='bpcode w800'>
	<ja>@Rest</ja>(
		path=<js>"/petstore"</js>,
		title=<js>"Petstore application"</js>,
		...
		swagger=<ja>@ResourceSwagger</ja>(
			version=<js>"1.0.0"</js>,
			title=<js>"Swagger Petstore"</js>,
			termsOfService=<js>"You are on your own."</js>,
			contact=<ja>@Contact</ja>(
				name=<js>"Juneau Development Team"</js>,
				email=<js>"dev@juneau.apache.org"</js>,
				url=<js>"http://juneau.apache.org"</js>
			),
			license=<ja>@License</ja>(
				name=<js>"Apache 2.0"</js>,
				url=<js>"http://www.apache.org/licenses/LICENSE-2.0.html"</js>
			),
			externalDocs=<ja>@ExternalDocs</ja>(
				description=<js>"Find out more about Juneau"</js>,
				url=<js>"http://juneau.apache.org"</js>
			)
		),
		...
	)
	<jk>public class</jk> PetStoreResource <jk>extends</jk> BasicRestServletJena {...}
</p>
<p>
	All annotations support {@doc DefaultRestSvlVariables SVL variables}, so you could for example
	pull localized strings from resource bundles using {@link oajr.vars.LocalizationVar $L} variables.
</p>
<p class='bpcode w800'>
	<ja>@Rest</ja>(
		path=<js>"/petstore"</js>,
		title=<js>"Petstore application"</js>,
		messages=<js>"nls/MyMessages"</js>,
		...
		swagger=<ja>@ResourceSwagger</ja>(
			version=<js>"1.0.0"</js>,
			title=<js>"$L{myTitle}"</js>,
			termsOfService=<js>"$L{myTermsOfService}"</js>,
			contact=<ja>@Contact</ja>(
				name=<js>"$L{myTeam}"</js>,
				email=<js>"dev@juneau.apache.org"</js>,
				url=<js>"http://juneau.apache.org"</js>
			),
			license=<ja>@License</ja>(
				name=<js>"Apache 2.0"</js>,
				url=<js>"http://www.apache.org/licenses/LICENSE-2.0.html"</js>
			),
			externalDocs=<ja>@ExternalDocs</ja>(
				description=<js>"$L{myExternalDocsDescription}"</js>,
				url=<js>"http://juneau.apache.org"</js>
			)
		),
		...
	)
	<jk>public class</jk> PetStoreResource <jk>extends</jk> BasicRestServletJena {...}
</p>
<p>
	A third option is to define your Swagger information in your {@link oajr.annotation.Rest#messages @Rest(messages)} resource
	bundle using predefined Swagger keywords:
</p>
<p class='bpcode w800'>
	<mk>PetStoreResource.version</mk> = <mv>1.0.0</mv>
	<mk>PetStoreResource.title</mk> = <mv>Swagger Petstore</mv>
	<mk>PetStoreResource.termsOfService</mk> = <mv>You are on your own.</mv>
	<mk>PetStoreResource.contact</mk> = <mv>{name:'Juneau Development Team', email:'dev@juneau.apache.org',...}</mv>
	<mk>PetStoreResource.license</mk> = <mv>{name:'Apache 2.0',...}</mv>
	<mk>PetStoreResource.externalDocs</mk> = <mv>{description:'Find out more about Juneau',...}</mv>
</p>
<p>
	Information defined in multiple locations are merged into a single set of data.  
	When the same information is provided in multiple locations, the following order-of-precedence is used:
</p>
<ol>
	<li>Java annotations
	<li>Resource bundle
	<li>Swagger JSON file
</ol>