| <!-- |
| /*************************************************************************************************************************** |
| * 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. |
| ***************************************************************************************************************************/ |
| --> |
| |
| Swagger |
| |
| <p> |
| The Juneau Swagger DTOs are simply beans with fluent-style setters that allow you to quickly construct |
| Swagger documents as Java objects. |
| These object can then be serialized to JSON using one of the existing JSON serializers, or to other |
| languages such as XML or HTML using the other serializers. |
| </p> |
| <p> |
| The {@link oaj.dto.swagger.SwaggerBuilder} class is a utility class with predefined static |
| methods that allow you to easily construct DTO instances in a minimal amount of code. |
| </p> |
| <p> |
| The following is an example Swagger document from the |
| <a href='http://petstore.swagger.io/'>Swagger website</a>. |
| </p> |
| <p class='bpcode w800'> |
| { |
| <jok>"swagger"</jok>: <jov>"2.0"</jov>, |
| <jok>"info"</jok>: { |
| <jok>"title"</jok>: <jov>"Swagger Petstore"</jov>, |
| <jok>"description"</jok>: <jov>"This is a sample server Petstore server."</jov>, |
| <jok>"version"</jok>: <jov>"1.0.0"</jov>, |
| <jok>"termsOfService"</jok>: <jov>"http://swagger.io/terms/"</jov>, |
| <jok>"contact"</jok>: { |
| <jok>"email"</jok>: <jov>"apiteam@swagger.io"</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>"host"</jok>: <jov>"petstore.swagger.io"</jov>, |
| <jok>"basePath"</jok>: <jov>"/v2"</jov>, |
| <jok>"tags"</jok>: [ |
| { |
| <jok>"name"</jok>: <jov>"pet"</jov>, |
| <jok>"description"</jok>: <jov>"Everything about your Pets"</jov>, |
| <jok>"externalDocs"</jok>: { |
| <jok>"description"</jok>: <jov>"Find out more"</jov>, |
| <jok>"url"</jok>: <jov>"http://swagger.io"</jov> |
| } |
| } |
| ], |
| <jok>"schemes"</jok>: [ |
| <jov>"http"</jov> |
| ], |
| <jok>"paths"</jok>: { |
| <jok>"/pet"</jok>: { |
| <jok>"post"</jok>: { |
| <jok>"tags"</jok>: [ |
| <jov>"pet"</jov> |
| ], |
| <jok>"summary"</jok>: <jov>"Add a new pet to the store"</jov>, |
| <jok>"description"</jok>: <jov>""</jov>, |
| <jok>"operationId"</jok>: <jov>"addPet"</jov>, |
| <jok>"consumes"</jok>: [ |
| <jov>"application/json"</jov>, |
| <jov>"text/xml"</jov> |
| ], |
| <jok>"produces"</jok>: [ |
| <jov>"application/json"</jov>, |
| <jov>"text/xml"</jov> |
| ], |
| <jok>"parameters"</jok>: [ |
| { |
| <jok>"in"</jok>: <jov>"body"</jov>, |
| <jok>"name"</jok>: <jov>"body"</jov>, |
| <jok>"description"</jok>: <jov>"Pet object that needs to be added to the store"</jov>, |
| <jok>"required"</jok>: <jov>true</jov> |
| } |
| ], |
| <jok>"responses"</jok>: { |
| <jok>"405"</jok>: { |
| <jok>"description"</jok>: <jov>"Invalid input"</jov> |
| } |
| } |
| } |
| } |
| } |
| } |
| </p> |
| <p> |
| This document can be generated by the following Java code: |
| </p> |
| <p class='bpcode w800'> |
| <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>)) |
| ); |
| |
| <jc>// Serialize using JSON serializer.</jc> |
| String swaggerJson = JsonSerializer.<jsf>DEFAULT_READABLE</jsf>.serialize(swagger); |
| |
| <jc>// Or just use toString().</jc> |
| String swaggerJson = swagger.toString(); |
| </p> |
| <p> |
| Methods that take in beans and collections of beans can also take in JSON representations |
| of those objects. |
| </p> |
| <p class='bpcode w800'> |
| <jc>// Pass in a JSON object representation of an Info object.</jc> |
| swagger.info(<js>"{title:'Swagger Petstore',...}"</js>); |
| </p> |
| <p> |
| Properties can also be accessed via the {@link oaj.dto.swagger.SwaggerElement#get(String,Class)} |
| and {@link oaj.dto.swagger.SwaggerElement#set(String,Object)} methods. |
| These methods can also be used to set and retrieve non-Swagger attributes such as |
| <js>"$ref"</js> (which is not a part of the Swagger spec, but is part of the JSON Schema spec). |
| </p> |
| <p class='bpcode w800'> |
| <jc>// Set a non-standard attribute.</jc> |
| swagger.set(<js>"$ref"</js>, <js>"http://foo.com"</js>); |
| |
| <jc>// Retrieve a non-standard attribute.</jc> |
| URI ref = swagger.get(<js>"$ref"</js>, URI.<jk>class</jk>); |
| </p> |
| <p> |
| Swagger docs can be parsed back into Swagger beans using the following code: |
| </p> |
| <p class='bpcode w800'> |
| Swagger swagger = JsonParser.<jsf>DEFAULT</jsf>.parse(swaggerJson, Swagger.<jk>class</jk>); |
| </p> |