http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/75b0d8ee/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SecurityScheme.java ---------------------------------------------------------------------- diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SecurityScheme.java b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SecurityScheme.java new file mode 100644 index 0000000..547ac3c --- /dev/null +++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SecurityScheme.java @@ -0,0 +1,428 @@ +// *************************************************************************************************************************** +// * 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. * +// *************************************************************************************************************************** +package org.apache.juneau.dto.swagger; + +import static org.apache.juneau.internal.ArrayUtils.*; + +import java.util.*; + +import org.apache.juneau.*; +import org.apache.juneau.annotation.*; + +/** + * Allows the definition of a security scheme that can be used by the operations. + * + * <p> + * Supported schemes are basic authentication, an API key (either as a header or as a query parameter) and OAuth2's + * common flows (implicit, password, application and access code). + * + * <h5 class='section'>Example:</h5> + * <p class='bcode'> + * <jc>// Basic authentication sample</jc> + * { + * <js>"type"</js>: <js>"basic"</js> + * } + * + * <jc>// API key sample</jc> + * { + * <js>"type"</js>: <js>"apiKey"</js>, + * <js>"name"</js>: <js>"api_key"</js>, + * <js>"in"</js>: <js>"header"</js> + * } + * + * <jc>// Implicit OAuth2 sample</jc> + * { + * <js>"type"</js>: <js>"oauth2"</js>, + * <js>"authorizationUrl"</js>: <js>"http://swagger.io/api/oauth/dialog";</js>, + * <js>"flow"</js>: <js>"implicit"</js>, + * <js>"scopes"</js>: { + * <js>"write:pets"</js>: <js>"modify pets in your account"</js>, + * <js>"read:pets"</js>: <js>"read your pets"</js> + * } + * } + * </p> + * + * <h6 class='topic'>Additional Information</h6> + * <ul class='doctree'> + * <li class='link'> + * <a class='doclink' href='../../../../../overview-summary.html#DTOs'>Juneau Data Transfer Objects + * (org.apache.juneau.dto)</a> + * <ul> + * <li class='sublink'> + * <a class='doclink' href='../../../../../overview-summary.html#DTOs.Swagger'>Swagger</a> + * </ul> + * </li> + * <li class='jp'> + * <a class='doclink' href='package-summary.html#TOC'>org.apache.juneau.dto.swagger</a> + * </li> + * </ul> + */ +@Bean(properties="type,description,name,in,flow,authorizationUrl,tokenUrl,scopes") +@SuppressWarnings("hiding") +public class SecurityScheme extends SwaggerElement { + + private static final String[] VALID_TYPES = {"basic", "apiKey", "oauth2"}; + + private String type; + private String description; + private String name; + private String in; + private String flow; + private String authorizationUrl; + private String tokenUrl; + private Map<String,String> scopes; + + @Override /* SwaggerElement */ + protected SecurityScheme strict() { + super.strict(); + return this; + } + + /** + * Bean property getter: <property>type</property>. + * + * <p> + * Required. The type of the security scheme. + * + * <p> + * Valid values are <js>"basic"</js>, <js>"apiKey"</js> or <js>"oauth2"</js>. + * + * @return The value of the <property>type</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public String getType() { + return type; + } + + /** + * Bean property setter: <property>type</property>. + * + * <p> + * Required. The type of the security scheme. + * + * <p> + * Valid values are <js>"basic"</js>, <js>"apiKey"</js> or <js>"oauth2"</js>. + * + * @param type The new value for the <property>type</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme setType(String type) { + if (isStrict() && ! contains(type, VALID_TYPES)) + throw new FormattedRuntimeException( + "Invalid value passed in to setType(String). Value=''{0}'', valid values={1}", + type, VALID_TYPES + ); + this.type = type; + return this; + } + + /** + * Synonym for {@link #setType(String)}. + * + * @param type The new value for the <property>type</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme type(String type) { + return setType(type); + } + + /** + * Bean property getter: <property>description</property>. + * + * <p> + * A short description for security scheme. + * + * @return + * The value of the <property>description</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public String getDescription() { + return description; + } + + /** + * Bean property setter: <property>description</property>. + * + * <p> + * A short description for security scheme. + * + * @param description The new value for the <property>description</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme setDescription(String description) { + this.description = description; + return this; + } + + /** + * Synonym for {@link #setDescription(String)}. + * + * @param description The new value for the <property>description</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme description(String description) { + return setDescription(description); + } + + /** + * Bean property getter: <property>name</property>. + * + * <p> + * The name of the header or query parameter to be used. + * + * @return The value of the <property>name</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public String getName() { + return name; + } + + /** + * Bean property setter: <property>name</property>. + * + * <p> + * The name of the header or query parameter to be used. + * + * @param name The new value for the <property>name</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme setName(String name) { + this.name = name; + return this; + } + + /** + * Synonym for {@link #setName(String)}. + * + * @param name The new value for the <property>name</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme name(String name) { + return setName(name); + } + + /** + * Bean property getter: <property>in</property>. + * + * <p> + * The location of the API key. Valid values are <js>"query"</js> or <js>"header"</js>. + * + * @return The value of the <property>in</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public String getIn() { + return in; + } + + /** + * Bean property setter: <property>in</property>. + * + * <p> + * The location of the API key. Valid values are <js>"query"</js> or <js>"header"</js>. + * + * @param in The new value for the <property>in</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme setIn(String in) { + this.in = in; + return this; + } + + /** + * Synonym for {@link #setIn(String)}. + * + * @param in The new value for the <property>in</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme in(String in) { + return setIn(in); + } + + /** + * Bean property getter: <property>flow</property>. + * + * <p> + * The flow used by the OAuth2 security scheme. + * + * <p> + * Valid values are <js>"implicit"</js>, <js>"password"</js>, <js>"application"</js> or <js>"accessCode"</js>. + * + * @return The value of the <property>flow</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public String getFlow() { + return flow; + } + + /** + * Bean property setter: <property>flow</property>. + * + * <p> + * The flow used by the OAuth2 security scheme. + * + * <p> + * Valid values are <js>"implicit"</js>, <js>"password"</js>, <js>"application"</js> or <js>"accessCode"</js>. + * + * @param flow The new value for the <property>flow</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme setFlow(String flow) { + this.flow = flow; + return this; + } + + /** + * Synonym for {@link #setFlow(String)}. + * + * @param flow The new value for the <property>flow</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme flow(String flow) { + return setFlow(flow); + } + + /** + * Bean property getter: <property>authorizationUrl</property>. + * + * <p> + * The authorization URL to be used for this flow. + * + * <p> + * This SHOULD be in the form of a URL. + * + * @return + * The value of the <property>authorizationUrl</property> property on this bean, or <jk>null</jk> if it + * is not set. + */ + public String getAuthorizationUrl() { + return authorizationUrl; + } + + /** + * Bean property setter: <property>authorizationUrl</property>. + * + * <p> + * The authorization URL to be used for this flow. + * + * <p> + * This SHOULD be in the form of a URL. + * + * @param authorizationUrl The new value for the <property>authorizationUrl</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme setAuthorizationUrl(String authorizationUrl) { + this.authorizationUrl = authorizationUrl; + return this; + } + + /** + * Synonym for {@link #setAuthorizationUrl(String)}. + * + * @param authorizationUrl The new value for the <property>authorizationUrl</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme authorizationUrl(String authorizationUrl) { + return setAuthorizationUrl(authorizationUrl); + } + + /** + * Bean property getter: <property>tokenUrl</property>. + * + * <p> + * The token URL to be used for this flow. + * + * <p> + * This SHOULD be in the form of a URL. + * + * @return The value of the <property>tokenUrl</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public String getTokenUrl() { + return tokenUrl; + } + + /** + * Bean property setter: <property>tokenUrl</property>. + * + * <p> + * The token URL to be used for this flow. + * + * <p> + * This SHOULD be in the form of a URL. + * + * @param tokenUrl The new value for the <property>tokenUrl</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme setTokenUrl(String tokenUrl) { + this.tokenUrl = tokenUrl; + return this; + } + + /** + * Synonym for {@link #setTokenUrl(String)}. + * + * @param tokenUrl The new value for the <property>tokenUrl</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme tokenUrl(String tokenUrl) { + return setTokenUrl(tokenUrl); + } + + /** + * Bean property getter: <property>scopes</property>. + * + * <p> + * The available scopes for the OAuth2 security scheme. + * + * @return The value of the <property>scopes</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public Map<String,String> getScopes() { + return scopes; + } + + /** + * Bean property setter: <property>scopes</property>. + * + * <p> + * The available scopes for the OAuth2 security scheme. + * + * @param scopes The new value for the <property>scopes</property> property on this bean. + * @return This object (for method chaining). + */ + public SecurityScheme setScopes(Map<String,String> scopes) { + this.scopes = scopes; + return this; + } + + /** + * Bean property adder: <property>scopes</property>. + * + * <p> + * The available scopes for the OAuth2 security scheme. + * + * @param name The name of the scope. + * @param description A short description of the scope. + * @return This object (for method chaining). + */ + public SecurityScheme addScope(String name, String description) { + if (scopes == null) + scopes = new TreeMap<String,String>(); + scopes.put(name, description); + return this; + } + + /** + * Synonym for {@link #addScope(String,String)}. + * + * @param name The name of the scope. + * @param description A short description of the scope. + * @return This object (for method chaining). + */ + public SecurityScheme scope(String name, String description) { + return addScope(name, description); + } +}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/75b0d8ee/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Swagger.java ---------------------------------------------------------------------- diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Swagger.java b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Swagger.java new file mode 100644 index 0000000..8500444 --- /dev/null +++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Swagger.java @@ -0,0 +1,1037 @@ +// *************************************************************************************************************************** +// * 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. * +// *************************************************************************************************************************** +package org.apache.juneau.dto.swagger; + +import java.util.*; + +import org.apache.juneau.annotation.*; +import org.apache.juneau.http.*; +import org.apache.juneau.utils.*; + +/** + * This is the root document object for the API specification. + * + * <h6 class='topic'>Additional Information</h6> + * <ul class='doctree'> + * <li class='link'> + * <a class='doclink' href='../../../../../overview-summary.html#DTOs'>Juneau Data Transfer Objects + * (org.apache.juneau.dto)</a> + * <ul> + * <li class='sublink'> + * <a class='doclink' href='../../../../../overview-summary.html#DTOs.Swagger'>Swagger</a> + * </ul> + * </li> + * <li class='jp'> + * <a class='doclink' href='package-summary.html#TOC'>org.apache.juneau.dto.swagger</a> + * </li> + * </ul> + */ +@Bean(properties="swagger,info,tags,externalDocs,basePath,schemes,consumes,produces,paths,definitions,parameters,responses,securityDefinitions,security") +@SuppressWarnings("hiding") +public class Swagger extends SwaggerElement { + + /** Represents a null swagger */ + public static final Swagger NULL = new Swagger(); + + private String swagger = "2.0"; + private Info info; + private String host, basePath; + private List<String> schemes; + private List<MediaType> consumes; + private List<MediaType> produces; + private Map<String,Map<String,Operation>> paths; + private Map<String,SchemaInfo> definitions; + private Map<String,ParameterInfo> parameters; + private Map<String,ResponseInfo> responses; + private Map<String,SecurityScheme> securityDefinitions; + private List<Map<String,List<String>>> security; + private List<Tag> tags; + private ExternalDocumentation externalDocs; + + /** + * Bean property getter: <property>swagger</property>. + * + * <p> + * Required. Specifies the Swagger Specification version being used. + * + * <p> + * It can be used by the Swagger UI and other clients to interpret the API listing. + * The value MUST be <js>"2.0"</js>. + * + * @return The value of the <property>swagger</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public String getSwagger() { + return swagger; + } + + /** + * Bean property setter: <property>swagger</property>. + * + * <p> + * Required. Specifies the Swagger Specification version being used. + * + * <p> + * It can be used by the Swagger UI and other clients to interpret the API listing. + * The value MUST be <js>"2.0"</js>. + * + * @param swagger The new value for the <property>swagger</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setSwagger(String swagger) { + this.swagger = swagger; + return this; + } + + /** + * Synonym for {@link #setSwagger(String)}. + * + * @param swagger The new value for the <property>swagger</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger swagger(String swagger) { + return setSwagger(swagger); + } + + /** + * Bean property getter: <property>info</property>. + * + * <p> + * Required. Provides metadata about the API. + * + * <p> + * The metadata can be used by the clients if needed. + * + * @return The value of the <property>info</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public Info getInfo() { + return info; + } + + /** + * Bean property setter: <property>info</property>. + * + * <p> + * Required. Provides metadata about the API. + * + * <p> + * The metadata can be used by the clients if needed. + * + * @param info The new value for the <property>info</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setInfo(Info info) { + this.info = info; + return this; + } + + /** + * Synonym for {@link #setInfo(Info)}. + * + * @param info The new value for the <property>info</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger info(Info info) { + return setInfo(info); + } + + /** + * Bean property getter: <property>host</property>. + * + * <p> + * The host (name or IP) serving the API. + * + * <p> + * This MUST be the host only and does not include the scheme nor sub-paths. + * It MAY include a port. + * If the host is not included, the host serving the documentation is to be used (including the port). + * The host does not support <a class="doclink" href="http://swagger.io/specification/#pathTemplating";> + * path templating</a>. + * + * @return The value of the <property>host</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public String getHost() { + return host; + } + + /** + * Bean property setter: <property>host</property>. + * + * <p> + * The host (name or IP) serving the API. + * + * <p> + * This MUST be the host only and does not include the scheme nor sub-paths. + * It MAY include a port. + * If the host is not included, the host serving the documentation is to be used (including the port). + * The host does not support <a class="doclink" href="http://swagger.io/specification/#pathTemplating";> + * path templating</a>. + * + * @param host The new value for the <property>host</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setHost(String host) { + this.host = host; + return this; + } + + /** + * Synonym for {@link #setHost(String)}. + * + * @param host The new value for the <property>host</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger host(String host) { + return setHost(host); + } + + /** + * Bean property getter: <property>basePath</property>. + * + * <p> + * The base path on which the API is served, which is relative to the <code>host</code>. + * + * <p> + * If it is not included, the API is served directly under the <code>host</code>. + * The value MUST start with a leading slash (/). + * The <code>basePath</code> does not support <a class="doclink" + * href="http://swagger.io/specification/#pathTemplating";>path templating</a>. + * + * @return The value of the <property>basePath</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public String getBasePath() { + return basePath; + } + + /** + * Bean property setter: <property>basePath</property>. + * + * <p> + * The base path on which the API is served, which is relative to the <code>host</code>. + * + * <p> + * If it is not included, the API is served directly under the <code>host</code>. + * The value MUST start with a leading slash (/). + * The <code>basePath</code> does not support <a class="doclink" + * href="http://swagger.io/specification/#pathTemplating";>path templating</a>. + * + * @param basePath The new value for the <property>basePath</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setBasePath(String basePath) { + this.basePath = basePath; + return this; + } + + /** + * Synonym for {@link #setBasePath(String)}. + * + * @param basePath The new value for the <property>basePath</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger basePath(String basePath) { + return setBasePath(basePath); + } + + /** + * Bean property getter: <property>schemes</property>. + * + * <p> + * The transfer protocol of the API. + * + * <p> + * Values MUST be from the list: <js>"http"</js>, <js>"https"</js>, <js>"ws"</js>, <js>"wss"</js>. + * If the <code>schemes</code> is not included, the default scheme to be used is the one used to access the Swagger + * definition itself. + * + * @return The value of the <property>schemes</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public List<String> getSchemes() { + return schemes; + } + + /** + * Bean property setter: <property>schemes</property>. + * + * <p> + * The transfer protocol of the API. + * + * <p> + * Values MUST be from the list: <js>"http"</js>, <js>"https"</js>, <js>"ws"</js>, <js>"wss"</js>. + * If the <code>schemes</code> is not included, the default scheme to be used is the one used to access the Swagger + * definition itself. + * + * @param schemes The new value for the <property>schemes</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setSchemes(List<String> schemes) { + this.schemes = schemes; + return this; + } + + /** + * Bean property adder: <property>schemes</property>. + * + * <p> + * The transfer protocol of the API. + * + * <p> + * Values MUST be from the list: <js>"http"</js>, <js>"https"</js>, <js>"ws"</js>, <js>"wss"</js>. + * If the <code>schemes</code> is not included, the default scheme to be used is the one used to access the Swagger + * definition itself. + * + * @param schemes The values to add for the <property>schemes</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger addSchemes(String...schemes) { + return addSchemes(Arrays.asList(schemes)); + } + + /** + * Bean property adder: <property>schemes</property>. + * + * <p> + * The transfer protocol of the API. + * + * <p> + * Values MUST be from the list: <js>"http"</js>, <js>"https"</js>, <js>"ws"</js>, <js>"wss"</js>. + * If the <code>schemes</code> is not included, the default scheme to be used is the one used to access the Swagger + * definition itself. + * + * @param schemes The values to add for the <property>schemes</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger addSchemes(Collection<String> schemes) { + if (schemes != null) { + if (this.schemes == null) + this.schemes = new LinkedList<String>(); + this.schemes.addAll(schemes); + } + return this; + } + + /** + * Synonym for {@link #addSchemes(String...)}. + * + * @param schemes The values to add for the <property>schemes</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger schemes(String...schemes) { + return addSchemes(schemes); + } + + /** + * Bean property getter: <property>consumes</property>. + * + * <p> + * A list of MIME types the APIs can consume. + * + * <p> + * This is global to all APIs but can be overridden on specific API calls. + * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes";> + * Mime Types</a>. + * + * @return The value of the <property>consumes</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public List<MediaType> getConsumes() { + return consumes; + } + + /** + * Bean property setter: <property>consumes</property>. + * + * <p> + * A list of MIME types the APIs can consume. + * + * <p> + * This is global to all APIs but can be overridden on specific API calls. + * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes";> + * Mime Types</a>. + * + * @param consumes The new value for the <property>consumes</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setConsumes(List<MediaType> consumes) { + this.consumes = consumes; + return this; + } + + /** + * Bean property adder: <property>consumes</property>. + * + * <p> + * A list of MIME types the APIs can consume. + * + * <p> + * This is global to all APIs but can be overridden on specific API calls. + * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes";> + * Mime Types</a>. + * + * @param consumes The values to add for the <property>consumes</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger addConsumes(MediaType...consumes) { + return addConsumes(Arrays.asList(consumes)); + } + + /** + * Bean property adder: <property>consumes</property>. + * + * <p> + * A list of MIME types the APIs can consume. + * + * <p> + * This is global to all APIs but can be overridden on specific API calls. + * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes";> + * Mime Types</a>. + * + * @param consumes The values to add for the <property>consumes</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger addConsumes(Collection<MediaType> consumes) { + if (consumes != null) { + if (this.consumes == null) + this.consumes = new LinkedList<MediaType>(); + this.consumes.addAll(consumes); + } + return this; + } + + /** + * Synonym for {@link #addConsumes(MediaType...)}. + * + * @param consumes The values to add for the <property>consumes</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger consumes(MediaType...consumes) { + return addConsumes(consumes); + } + + /** + * Synonym for {@link #addConsumes(Collection)}. + * + * @param consumes The values to add for the <property>consumes</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger consumes(Collection<MediaType> consumes) { + return addConsumes(consumes); + } + + /** + * Bean property getter: <property>produces</property>. + * + * <p> + * A list of MIME types the APIs can produce. + * + * <p> + * This is global to all APIs but can be overridden on specific API calls. + * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes";> + * Mime Types</a>. + * + * @return The value of the <property>produces</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public List<MediaType> getProduces() { + return produces; + } + + /** + * Bean property setter: <property>produces</property>. + * + * <p> + * A list of MIME types the APIs can produce. + * + * <p> + * This is global to all APIs but can be overridden on specific API calls. + * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes";> + * Mime Types</a>. + * + * @param produces The new value for the <property>produces</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setProduces(List<MediaType> produces) { + this.produces = produces; + return this; + } + + /** + * Bean property adder: <property>produces</property>. + * + * <p> + * A list of MIME types the APIs can produce. + * + * <p> + * This is global to all APIs but can be overridden on specific API calls. + * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes";> + * Mime Types</a>. + * + * @param produces The values to add for the <property>produces</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger addProduces(MediaType...produces) { + return addProduces(Arrays.asList(produces)); + } + + /** + * Bean property adder: <property>produces</property>. + * + * <p> + * A list of MIME types the APIs can produce. + * + * <p> + * This is global to all APIs but can be overridden on specific API calls. + * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes";> + * Mime Types</a>. + * + * @param produces The values to add for the <property>produces</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger addProduces(Collection<MediaType> produces) { + if (produces != null) { + if (this.produces == null) + this.produces = new LinkedList<MediaType>(); + this.produces.addAll(produces); + } + return this; + } + + /** + * Synonym for {@link #addProduces(MediaType...)}. + * + * @param produces The values to add for the <property>produces</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger produces(MediaType...produces) { + return addProduces(produces); + } + + /** + * Synonym for {@link #addProduces(Collection)}. + * + * @param produces The values to add for the <property>produces</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger produces(Collection<MediaType> produces) { + return addProduces(produces); + } + + /** + * Bean property getter: <property>paths</property>. + * + * <p> + * Required. The available paths and operations for the API. + * + * @return The value of the <property>paths</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public Map<String,Map<String,Operation>> getPaths() { + return paths; + } + + /** + * Bean property setter: <property>paths</property>. + * + * <p> + * Required. The available paths and operations for the API. + * + * @param paths The new value for the <property>paths</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setPaths(Map<String,Map<String,Operation>> paths) { + this.paths = paths; + return this; + } + + /** + * Bean property adder: <property>paths</property>. + * + * <p> + * Required. The available paths and operations for the API. + * + * @param path The path template. + * @param methodName The HTTP method name. + * @param operation The operation that describes the path. + * @return This object (for method chaining). + */ + public Swagger addPath(String path, String methodName, Operation operation) { + if (paths == null) + paths = new TreeMap<String,Map<String,Operation>>(); + Map<String,Operation> p = paths.get(path); + if (p == null) { + p = new TreeMap<String,Operation>(new MethodSorter()); + paths.put(path, p); + } + p.put(methodName, operation); + return this; + } + + /** + * Synonym for {@link #path(String,String,Operation)}. + * + * @param path The path template. + * @param methodName The HTTP method name. + * @param operation The operation that describes the path. + * @return This object (for method chaining). + */ + public Swagger path(String path, String methodName, Operation operation) { + return addPath(path, methodName, operation); + } + + /** + * Bean property getter: <property>definitions</property>. + * + * <p> + * An object to hold data types produced and consumed by operations. + * + * @return + * The value of the <property>definitions</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public Map<String,SchemaInfo> getDefinitions() { + return definitions; + } + + /** + * Bean property setter: <property>definitions</property>. + * + * <p> + * An object to hold data types produced and consumed by operations. + * + * @param definitions The new value for the <property>definitions</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setDefinitions(Map<String,SchemaInfo> definitions) { + this.definitions = definitions; + return this; + } + + /** + * Bean property adder: <property>definitions</property>. + * + * <p> + * An object to hold data types produced and consumed by operations. + * + * @param name A definition name. + * @param schema The schema that the name defines. + * @return This object (for method chaining). + */ + public Swagger addDefinition(String name, SchemaInfo schema) { + if (definitions == null) + definitions = new TreeMap<String,SchemaInfo>(); + definitions.put(name, schema); + return this; + } + + /** + * Synonym for {@link #addDefinition(String,SchemaInfo)}. + * + * @param name A definition name. + * @param schema The schema that the name defines. + * @return This object (for method chaining). + */ + public Swagger xxx(String name, SchemaInfo schema) { + return addDefinition(name, schema); + } + + /** + * Bean property getter: <property>parameters</property>. + * + * <p> + * An object to hold parameters that can be used across operations. + * + * <p> + * This property does not define global parameters for all operations. + * + * @return The value of the <property>parameters</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public Map<String,ParameterInfo> getParameters() { + return parameters; + } + + /** + * Bean property setter: <property>parameters</property>. + * + * <p> + * An object to hold parameters that can be used across operations. + * + * <p> + * This property does not define global parameters for all operations. + * + * @param parameters The new value for the <property>parameters</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setParameters(Map<String,ParameterInfo> parameters) { + this.parameters = parameters; + return this; + } + + /** + * Bean property adder: <property>parameters</property>. + * + * <p> + * An object to hold parameters that can be used across operations. + * + * <p> + * This property does not define global parameters for all operations. + * + * @param name The parameter name. + * @param parameter The parameter definition. + * @return This object (for method chaining). + */ + public Swagger addParameter(String name, ParameterInfo parameter) { + if (parameters == null) + parameters = new TreeMap<String,ParameterInfo>(); + parameters.put(name, parameter); + return this; + } + + /** + * Synonym for {@link #addParameter(String,ParameterInfo)}. + * + * @param name The parameter name. + * @param parameter The parameter definition. + * @return This object (for method chaining). + */ + public Swagger parameter(String name, ParameterInfo parameter) { + return addParameter(name, parameter); + } + + /** + * Bean property getter: <property>responses</property>. + * + * <p> + * An object to hold responses that can be used across operations. + * + * <p> + * This property does not define global responses for all operations. + * + * @return The value of the <property>responses</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public Map<String,ResponseInfo> getResponses() { + return responses; + } + + /** + * Bean property setter: <property>responses</property>. + * + * <p> + * An object to hold responses that can be used across operations. + * + * <p> + * This property does not define global responses for all operations. + * + * @param responses The new value for the <property>responses</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setResponses(Map<String,ResponseInfo> responses) { + this.responses = responses; + return this; + } + + /** + * Bean property adder: <property>responses</property>. + * + * <p> + * An object to hold responses that can be used across operations. + * + * <p> + * This property does not define global responses for all operations. + * + * @param name The response name. + * @param response The response definition. + * @return This object (for method chaining). + */ + public Swagger addResponse(String name, ResponseInfo response) { + if (responses == null) + responses = new TreeMap<String,ResponseInfo>(); + responses.put(name, response); + return this; + } + + /** + * Synonym for {@link #addResponse(String,ResponseInfo)}. + * + * @param name The response name. + * @param response The response definition. + * @return This object (for method chaining). + */ + public Swagger response(String name, ResponseInfo response) { + return addResponse(name, response); + } + + /** + * Bean property getter: <property>securityDefinitions</property>. + * + * <p> + * Security scheme definitions that can be used across the specification. + * + * @return + * The value of the <property>securityDefinitions</property> property on this bean, or <jk>null</jk> if it + * is not set. + */ + public Map<String,SecurityScheme> getSecurityDefinitions() { + return securityDefinitions; + } + + /** + * Bean property setter: <property>securityDefinitions</property>. + * + * <p> + * Security scheme definitions that can be used across the specification. + * + * @param securityDefinitions The new value for the <property>securityDefinitions</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setSecurityDefinitions(Map<String,SecurityScheme> securityDefinitions) { + this.securityDefinitions = securityDefinitions; + return this; + } + + /** + * Bean property adder: <property>securityDefinitions</property>. + * + * <p> + * Security scheme definitions that can be used across the specification. + * + * @param name A security name. + * @param securityScheme A security schema. + * @return This object (for method chaining). + */ + public Swagger addSecurityDefinition(String name, SecurityScheme securityScheme) { + if (securityDefinitions == null) + securityDefinitions = new TreeMap<String,SecurityScheme>(); + securityDefinitions.put(name, securityScheme); + return this; + } + + /** + * Synonym for {@link #addSecurityDefinition(String,SecurityScheme)}. + * + * @param name A security name. + * @param securityScheme A security schema. + * @return This object (for method chaining). + */ + public Swagger securityDefinition(String name, SecurityScheme securityScheme) { + return addSecurityDefinition(name, securityScheme); + } + + /** + * Bean property getter: <property>security</property>. + * + * <p> + * A declaration of which security schemes are applied for the API as a whole. + * + * <p> + * The list of values describes alternative security schemes that can be used (that is, there is a logical OR + * between the security requirements). + * Individual operations can override this definition. + * + * @return The value of the <property>security</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public List<Map<String,List<String>>> getSecurity() { + return security; + } + + /** + * Bean property setter: <property>security</property>. + * + * <p> + * A declaration of which security schemes are applied for the API as a whole. + * + * <p> + * The list of values describes alternative security schemes that can be used (that is, there is a logical OR + * between the security requirements). + * Individual operations can override this definition. + * + * @param security The new value for the <property>security</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setSecurity(List<Map<String,List<String>>> security) { + this.security = security; + return this; + } + + /** + * Bean property adder: <property>security</property>. + * + * <p> + * A declaration of which security schemes are applied for the API as a whole. + * + * <p> + * The list of values describes alternative security schemes that can be used (that is, there is a logical OR + * between the security requirements). + * Individual operations can override this definition. + * + * @param security The value to add for the <property>security</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger addSecurity(Map<String,List<String>> security) { + if (this.security == null) + this.security = new LinkedList<Map<String,List<String>>>(); + this.security.add(security); + return this; + } + + /** + * Synonym for {@link #addSecurity(Map)}. + * + * @param scheme The security scheme that applies to this operation + * @param alternatives The list of values describes alternative security schemes that can be used (that is, there + * is a logical OR between the security requirements). + * @return This object (for method chaining). + */ + public Swagger security(String scheme, String...alternatives) { + Map<String,List<String>> m = new LinkedHashMap<String,List<String>>(); + m.put(scheme, Arrays.asList(alternatives)); + return addSecurity(m); + } + + /** + * Bean property getter: <property>tags</property>. + * + * <p> + * A list of tags used by the specification with additional metadata. + * + * <p> + * The order of the tags can be used to reflect on their order by the parsing tools. + * Not all tags that are used by the <a class="doclink" href="http://swagger.io/specification/#operationObject";> + * Operation Object</a> must be declared. + * The tags that are not declared may be organized randomly or based on the tools' logic. + * Each tag name in the list MUST be unique. + * + * @return The value of the <property>tags</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public List<Tag> getTags() { + return tags; + } + + /** + * Bean property setter: <property>tags</property>. + * + * <p> + * A list of tags used by the specification with additional metadata. + * + * <p> + * The order of the tags can be used to reflect on their order by the parsing tools. + * Not all tags that are used by the <a class="doclink" href="http://swagger.io/specification/#operationObject";> + * Operation Object</a> must be declared. + * The tags that are not declared may be organized randomly or based on the tools' logic. + * Each tag name in the list MUST be unique. + * + * @param tags The new value for the <property>tags</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setTags(List<Tag> tags) { + this.tags = tags; + return this; + } + + /** + * Bean property adder: <property>tags</property>. + * + * <p> + * A list of tags used by the specification with additional metadata. + * + * <p> + * The order of the tags can be used to reflect on their order by the parsing tools. + * Not all tags that are used by the <a class="doclink" href="http://swagger.io/specification/#operationObject";> + * Operation Object</a> must be declared. + * The tags that are not declared may be organized randomly or based on the tools' logic. + * Each tag name in the list MUST be unique. + * + * @param tags The values to add for the <property>tags</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger addTags(Tag...tags) { + if (this.tags == null) + this.tags = new LinkedList<Tag>(); + this.tags.addAll(Arrays.asList(tags)); + return this; + } + + /** + * Synonym for {@link #addTags(Tag...)}. + * + * @param tags The values to add for the <property>tags</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger tags(Tag...tags) { + return addTags(tags); + } + + /** + * Synonym for {@link #setTags(List)}. + * + * @param tags The values to add for the <property>tags</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger tags(List<Tag> tags) { + return setTags(tags); + } + + /** + * Bean property getter: <property>externalDocs</property>. + * + * <p> + * Additional external documentation. + * + * @return + * The value of the <property>externalDocs</property> property on this bean, or <jk>null</jk> if it is + * not set. + */ + public ExternalDocumentation getExternalDocs() { + return externalDocs; + } + + /** + * Bean property setter: <property>externalDocs</property>. + * + * <p> + * Additional external documentation. + * + * @param externalDocs The new value for the <property>externalDocs</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger setExternalDocs(ExternalDocumentation externalDocs) { + this.externalDocs = externalDocs; + return this; + } + + /** + * Synonym for {@link #setExternalDocs(ExternalDocumentation)}. + * + * @param externalDocs The new value for the <property>externalDocs</property> property on this bean. + * @return This object (for method chaining). + */ + public Swagger externalDocs(ExternalDocumentation externalDocs) { + return setExternalDocs(externalDocs); + } + + private static class MethodSorter implements Comparator<String> { + private final Map<String,Integer> methods = new AMap<String,Integer>() + .append("get",7) + .append("put",6) + .append("post",5) + .append("delete",4) + .append("options",3) + .append("head",2) + .append("patch",1); + + @Override + public int compare(String o1, String o2) { + Integer i1 = methods.get(o1); + Integer i2 = methods.get(o2); + if (i1 == null) + i1 = 0; + if (i2 == null) + i2 = 0; + return i2.compareTo(i1); + } + } +} http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/75b0d8ee/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerBuilder.java ---------------------------------------------------------------------- diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerBuilder.java b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerBuilder.java new file mode 100644 index 0000000..9e96614 --- /dev/null +++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerBuilder.java @@ -0,0 +1,358 @@ +// *************************************************************************************************************************** +// * 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. * +// *************************************************************************************************************************** +package org.apache.juneau.dto.swagger; + +import java.net.*; + +import org.apache.juneau.*; + +/** + * Various useful static methods for creating Swagger elements. + * + * <h6 class='topic'>Additional Information</h6> + * <ul class='doctree'> + * <li class='link'> + * <a class='doclink' href='../../../../../overview-summary.html#DTOs'>Juneau Data Transfer Objects + * (org.apache.juneau.dto)</a> + * <ul> + * <li class='sublink'> + * <a class='doclink' href='../../../../../overview-summary.html#DTOs.Swagger'>Swagger</a> + * </ul> + * </li> + * <li class='jp'> + * <a class='doclink' href='package-summary.html#TOC'>org.apache.juneau.dto.swagger</a> + * </li> + * </ul> + */ +public class SwaggerBuilder { + + /** + * Creates an empty {@link Contact} element. + * + * @return The new element. + */ + public static final Contact contact() { + return new Contact(); + } + + /** + * Creates an {@link Contact} element with the specified {@link Contact#name(String)} attribute. + * + * @param name The {@link Contact#name(String)} attribute. + * @return The new element. + */ + public static final Contact contact(String name) { + return contact().name(name); + } + + /** + * Creates an {@link Contact} element with the specified {@link Contact#name(String)}, {@link Contact#url(Object)}, + * and {@link Contact#email(String)}, attributes. + * + * @param name The {@link Contact#name(String)} attribute. + * @param url + * The {@link Contact#url(Object)} attribute. + * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}. + * <br>Strings must be valid URIs. + * <br>URIs defined by {@link UriResolver} can be used for values. + * @param email The {@link Contact#email(String)} attribute. + * @return The new element. + */ + public static final Contact contact(String name, Object url, String email) { + return contact().name(name).url(url).email(email); + } + + /** + * Creates an empty {@link ExternalDocumentation} element. + * + * @return The new element. + */ + public static final ExternalDocumentation externalDocumentation() { + return new ExternalDocumentation(); + } + + /** + * Creates an {@link ExternalDocumentation} element with the specified {@link ExternalDocumentation#url(Object)} + * attribute. + * + * @param url + * The {@link ExternalDocumentation#url(Object)} attribute. + * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}. + * <br>Strings must be valid URIs. + * <br>URIs defined by {@link UriResolver} can be used for values. + * @return The new element. + */ + public static final ExternalDocumentation externalDocumentation(Object url) { + return externalDocumentation().url(url); + } + + /** + * Creates an {@link ExternalDocumentation} element with the specified {@link ExternalDocumentation#url(Object)} + * and {@link ExternalDocumentation#description(String)} attributes. + * + * @param url + * The {@link ExternalDocumentation#url(Object)} attribute. + * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}. + * <br>Strings must be valid URIs. + * <br>URIs defined by {@link UriResolver} can be used for values. + * @param description The {@link ExternalDocumentation#description(String)} attribute. + * @return The new element. + */ + public static final ExternalDocumentation externalDocumentation(Object url, String description) { + return externalDocumentation().url(url).description(description); + } + + /** + * Creates an empty {@link HeaderInfo} element. + * + * @return The new element. + */ + public static final HeaderInfo headerInfo() { + return new HeaderInfo(); + } + + /** + * Creates an {@link HeaderInfo} element with the specified {@link HeaderInfo#type(String)} attribute. + * + * @param type The {@link HeaderInfo#type(String)} attribute. + * @return The new element. + */ + public static final HeaderInfo headerInfo(String type) { + return headerInfo().type(type); + } + + /** + * Creates an {@link HeaderInfo} element with the specified {@link HeaderInfo#type(String)} attribute. + * + * @param type The {@link HeaderInfo#type(String)} attribute. + * @return The new element. + */ + public static final HeaderInfo headerInfoStrict(String type) { + return headerInfo().strict().type(type); + } + + /** + * Creates an empty {@link Info} element. + * + * @return The new element. + */ + public static final Info info() { + return new Info(); + } + + /** + * Creates an {@link Info} element with the specified {@link Info#title(String)} and {@link Info#version(String)} + * attributes. + * + * @param title The {@link Info#title(String)} attribute. + * @param version The {@link Info#version(String)} attribute. + * @return The new element. + */ + public static final Info info(String title, String version) { + return info().title(title).version(version); + } + + /** + * Creates an empty {@link Items} element. + * + * @return The new element. + */ + public static final Items items() { + return new Items(); + } + + /** + * Creates an {@link Items} element with the specified {@link Items#type(String)} attribute. + * + * @param type The {@link Items#type(String)} attribute. + * @return The new element. + */ + public static final Items items(String type) { + return items().type(type); + } + + /** + * Creates an {@link Items} element with the specified {@link Items#type(String)} attribute. + * + * @param type The {@link Items#type(String)} attribute. + * @return The new element. + */ + public static final Items itemsStrict(String type) { + return items().strict().type(type); + } + + /** + * Creates an empty {@link License} element. + * + * @return The new element. + */ + public static final License license() { + return new License(); + } + + /** + * Creates an {@link License} element with the specified {@link License#name(String)} attribute. + * + * @param name The {@link License#name(String)} attribute. + * @return The new element. + */ + public static final License license(String name) { + return license().name(name); + } + + /** + * Creates an empty {@link Operation} element. + * + * @return The new element. + */ + public static final Operation operation() { + return new Operation(); + } + + /** + * Creates an empty {@link ParameterInfo} element. + * + * @return The new element. + */ + public static final ParameterInfo parameterInfo() { + return new ParameterInfo(); + } + + /** + * Creates an {@link ParameterInfo} element with the specified {@link ParameterInfo#in(String)} and + * {@link ParameterInfo#name(String)} attributes. + * + * @param in The {@link ParameterInfo#in(String)} attribute. + * @param name The {@link ParameterInfo#name(String)} attribute. + * @return The new element. + */ + public static final ParameterInfo parameterInfo(String in, String name) { + return parameterInfo().in(in).name(name); + } + + /** + * Creates an {@link ParameterInfo} element with the specified {@link ParameterInfo#in(String)} and + * {@link ParameterInfo#name(String)} attributes. + * + * @param in The {@link ParameterInfo#in(String)} attribute. + * @param name The {@link ParameterInfo#name(String)} attribute. + * @return The new element. + */ + public static final ParameterInfo parameterInfoStrict(String in, String name) { + return parameterInfo().strict().in(in).name(name); + } + + /** + * Creates an empty {@link ResponseInfo} element. + * + * @return The new element. + */ + public static final ResponseInfo responseInfo() { + return new ResponseInfo(); + } + + /** + * Creates an {@link ResponseInfo} element with the specified {@link ResponseInfo#description(String)} attribute. + * + * @param description The {@link ResponseInfo#description(String)} attribute. + * @return The new element. + */ + public static final ResponseInfo responseInfo(String description) { + return responseInfo().description(description); + } + + /** + * Creates an empty {@link SchemaInfo} element. + * + * @return The new element. + */ + public static final SchemaInfo schemaInfo() { + return new SchemaInfo(); + } + + /** + * Creates an empty {@link SecurityScheme} element. + * + * @return The new element. + */ + public static final SecurityScheme securityScheme() { + return new SecurityScheme(); + } + + /** + * Creates an {@link SecurityScheme} element with the specified {@link SecurityScheme#type(String)} attribute. + * + * @param type The {@link SecurityScheme#type(String)} attribute. + * @return The new element. + */ + public static final SecurityScheme securityScheme(String type) { + return securityScheme().type(type); + } + + /** + * Creates an {@link SecurityScheme} element with the specified {@link SecurityScheme#type(String)} attribute. + * + * @param type The {@link SecurityScheme#type(String)} attribute. + * @return The new element. + */ + public static final SecurityScheme securitySchemeStrict(String type) { + return securityScheme().strict().type(type); + } + + /** + * Creates an empty {@link Swagger} element. + * + * @return The new element. + */ + public static final Swagger swagger() { + return new Swagger(); + } + + /** + * Creates an {@link Swagger} element with the specified {@link Swagger#info(Info)} attribute. + * + * @param info The {@link Swagger#info(Info)} attribute. + * @return The new element. + */ + public static final Swagger swagger(Info info) { + return swagger().info(info); + } + + /** + * Creates an empty {@link Tag} element. + * + * @return The new element. + */ + public static final Tag tag() { + return new Tag(); + } + + /** + * Creates an {@link Tag} element with the specified {@link Tag#name(String)} attribute. + * + * @param name The {@link Tag#name(String)} attribute. + * @return The new element. + */ + public static final Tag tag(String name) { + return tag().name(name); + } + + /** + * Creates an empty {@link Xml} element. + * + * @return The new element. + */ + public static final Xml xml() { + return new Xml(); + } +} http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/75b0d8ee/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerElement.java ---------------------------------------------------------------------- diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerElement.java b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerElement.java new file mode 100644 index 0000000..ed41bdd --- /dev/null +++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerElement.java @@ -0,0 +1,55 @@ +// *************************************************************************************************************************** +// * 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. * +// *************************************************************************************************************************** +package org.apache.juneau.dto.swagger; + +/** + * Root class for all Swagger beans. + * + * <h6 class='topic'>Additional Information</h6> + * <ul class='doctree'> + * <li class='link'> + * <a class='doclink' href='../../../../../overview-summary.html#DTOs'>Juneau Data Transfer Objects + * (org.apache.juneau.dto)</a> + * <ul> + * <li class='sublink'> + * <a class='doclink' href='../../../../../overview-summary.html#DTOs.Swagger'>Swagger</a> + * </ul> + * </li> + * <li class='jp'> + * <a class='doclink' href='package-summary.html#TOC'>org.apache.juneau.dto.swagger</a> + * </li> + * </ul> + */ +public class SwaggerElement { + + private boolean strict; + + /** + * Returns <jk>true</jk> if contents should be validated per the Swagger spec. + * + * @return <jk>true</jk> if contents should be validated per the Swagger spec. + */ + protected boolean isStrict() { + return strict; + } + + /** + * Sets strict mode on this bean. + * + * @return This object (for method chaining). + */ + protected SwaggerElement strict() { + this.strict = true; + return this; + } +} http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/75b0d8ee/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Tag.java ---------------------------------------------------------------------- diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Tag.java b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Tag.java new file mode 100644 index 0000000..3e97616 --- /dev/null +++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Tag.java @@ -0,0 +1,171 @@ +// *************************************************************************************************************************** +// * 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. * +// *************************************************************************************************************************** +package org.apache.juneau.dto.swagger; + +import org.apache.juneau.annotation.*; + +/** + * Allows adding meta data to a single tag that is used by the <a class="doclink" href="http://swagger.io/specification/#operationObject";>Operation Object</a>. + * + * <p> + * It is not mandatory to have a Tag Object per tag used there. + * + * <h5 class='section'>Example:</h5> + * <p class='bcode'> + * { + * <js>"name"</js>: <js>"pet"</js>, + * <js>"description"</js>: <js>"Pets operations"</js> + * } + * </p> + * + * <h6 class='topic'>Additional Information</h6> + * <ul class='doctree'> + * <li class='link'> + * <a class='doclink' href='../../../../../overview-summary.html#DTOs'>Juneau Data Transfer Objects + * (org.apache.juneau.dto)</a> + * <ul> + * <li class='sublink'> + * <a class='doclink' href='../../../../../overview-summary.html#DTOs.Swagger'>Swagger</a> + * </ul> + * </li> + * <li class='jp'> + * <a class='doclink' href='package-summary.html#TOC'>org.apache.juneau.dto.swagger</a> + * </li> + * </ul> + */ +@Bean(properties="name,description,externalDocs") +@SuppressWarnings("hiding") +public class Tag extends SwaggerElement { + + private String name; + private String description; + private ExternalDocumentation externalDocs; + + /** + * Bean property getter: <property>name</property>. + * + * <p> + * Required. The name of the tag. + * + * @return The value of the <property>name</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public String getName() { + return name; + } + + /** + * Bean property setter: <property>name</property>. + * + * <p> + * Required. The name of the tag. + * + * @param name The new value for the <property>name</property> property on this bean. + * @return This object (for method chaining). + */ + public Tag setName(String name) { + this.name = name; + return this; + } + + /** + * Synonym for {@link #setName(String)}. + * + * @param name The new value for the <property>name</property> property on this bean. + * @return This object (for method chaining). + */ + public Tag name(String name) { + return setName(name); + } + + /** + * Bean property getter: <property>description</property>. + * + * <p> + * A short description for the tag. + * + * <p> + * <a class="doclink" href="https://help.github.com/articles/github-flavored-markdown";>GFM syntax</a> can be used + * for rich text representation. + * + * @return + * The value of the <property>description</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public String getDescription() { + return description; + } + + /** + * Bean property setter: <property>description</property>. + * + * <p> + * A short description for the tag. + * + * <p> + * <a class="doclink" href="https://help.github.com/articles/github-flavored-markdown";>GFM syntax</a> can be used + * for rich text representation. + * + * @param description The new value for the <property>description</property> property on this bean. + * @return This object (for method chaining). + */ + public Tag setDescription(String description) { + this.description = description; + return this; + } + + /** + * Synonym for {@link #setDescription(String)}. + * + * @param description The new value for the <property>description</property> property on this bean. + * @return This object (for method chaining). + */ + public Tag description(String description) { + return setDescription(description); + } + + /** + * Bean property getter: <property>externalDocs</property>. + * + * <p> + * Additional external documentation for this tag. + * + * @return + * The value of the <property>externalDocs</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public ExternalDocumentation getExternalDocs() { + return externalDocs; + } + + /** + * Bean property setter: <property>externalDocs</property>. + * + * <p> + * Additional external documentation for this tag. + * + * @param externalDocs The new value for the <property>externalDocs</property> property on this bean. + * @return This object (for method chaining). + */ + public Tag setExternalDocs(ExternalDocumentation externalDocs) { + this.externalDocs = externalDocs; + return this; + } + + /** + * Synonym for {@link #setExternalDocs(ExternalDocumentation)}. + * + * @param externalDocs The new value for the <property>externalDocs</property> property on this bean. + * @return This object (for method chaining). + */ + public Tag externalDocs(ExternalDocumentation externalDocs) { + return setExternalDocs(externalDocs); + } +} http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/75b0d8ee/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Xml.java ---------------------------------------------------------------------- diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Xml.java b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Xml.java new file mode 100644 index 0000000..39b7e53 --- /dev/null +++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Xml.java @@ -0,0 +1,264 @@ +// *************************************************************************************************************************** +// * 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. * +// *************************************************************************************************************************** +package org.apache.juneau.dto.swagger; + +import org.apache.juneau.annotation.*; + +/** + * A metadata object that allows for more fine-tuned XML model definitions. + * + * <p> + * When using arrays, XML element names are not inferred (for singular/plural forms) and the name property should be + * used to add that information. + * + * <h6 class='topic'>Additional Information</h6> + * <ul class='doctree'> + * <li class='link'> + * <a class='doclink' href='../../../../../overview-summary.html#DTOs'>Juneau Data Transfer Objects + * (org.apache.juneau.dto)</a> + * <ul> + * <li class='sublink'> + * <a class='doclink' href='../../../../../overview-summary.html#DTOs.Swagger'>Swagger</a> + * </ul> + * </li> + * <li class='jp'> + * <a class='doclink' href='package-summary.html#TOC'>org.apache.juneau.dto.swagger</a> + * </li> + * </ul> + */ +@Bean(properties="name,namespace,prefix,attribute,wrapped") +@SuppressWarnings("hiding") +public class Xml extends SwaggerElement { + + private String name; + private String namespace; + private String prefix; + private Boolean attribute; + private Boolean wrapped; + + /** + * Bean property getter: <property>name</property>. + * + * <p> + * Replaces the name of the element/attribute used for the described schema property. + * + * <p> + * When defined within the Items Object (<code>items</code>), it will affect the name of the individual XML elements + * within the list. + * When defined alongside <code>type</code> being array (outside the <code>items</code>), it will affect the + * wrapping element and only if wrapped is <jk>true</jk>. + * If wrapped is <jk>false</jk>, it will be ignored. + * + * @return The value of the <property>name</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public String getName() { + return name; + } + + /** + * Bean property setter: <property>name</property>. + * + * <p> + * Replaces the name of the element/attribute used for the described schema property. + * + * <p> + * When defined within the Items Object (<code>items</code>), it will affect the name of the individual XML elements + * within the list. + * When defined alongside <code>type</code> being array (outside the <code>items</code>), it will affect the + * wrapping element and only if wrapped is <jk>true</jk>. + * If wrapped is <jk>false</jk>, it will be ignored. + * + * @param name The new value for the <property>name</property> property on this bean. + * @return This object (for method chaining). + */ + public Xml setName(String name) { + this.name = name; + return this; + } + + /** + * Synonym for {@link #setName(String)}. + * + * @param name The new value for the <property>name</property> property on this bean. + * @return This object (for method chaining). + */ + public Xml name(String name) { + return setName(name); + } + + /** + * Bean property getter: <property>namespace</property>. + * + * <p> + * The URL of the namespace definition. Value SHOULD be in the form of a URL. + * + * @return The value of the <property>namespace</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public String getNamespace() { + return namespace; + } + + /** + * Bean property setter: <property>namespace</property>. + * + * <p> + * The URL of the namespace definition. Value SHOULD be in the form of a URL. + * + * @param namespace The new value for the <property>namespace</property> property on this bean. + * @return This object (for method chaining). + */ + public Xml setNamespace(String namespace) { + this.namespace = namespace; + return this; + } + + /** + * Synonym for {@link #setNamespace(String)}. + * + * @param namespace The new value for the <property>namespace</property> property on this bean. + * @return This object (for method chaining). + */ + public Xml namespace(String namespace) { + return setNamespace(namespace); + } + + /** + * Bean property getter: <property>prefix</property>. + * + * <p> + * The prefix to be used for the name. + * + * @return The value of the <property>prefix</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public String getPrefix() { + return prefix; + } + + /** + * Bean property setter: <property>prefix</property>. + * + * <p> + * The prefix to be used for the name. + * + * @param prefix The new value for the <property>prefix</property> property on this bean. + * @return This object (for method chaining). + */ + public Xml setPrefix(String prefix) { + this.prefix = prefix; + return this; + } + + /** + * Synonym for {@link #setPrefix(String)}. + * + * @param prefix The new value for the <property>prefix</property> property on this bean. + * @return This object (for method chaining). + */ + public Xml prefix(String prefix) { + return setPrefix(prefix); + } + + /** + * Bean property getter: <property>attribute</property>. + * + * <p> + * Declares whether the property definition translates to an attribute instead of an element. + * + * <p> + * Default value is <jk>false</jk>. + * + * @return The value of the <property>attribute</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public Boolean getAttribute() { + return attribute; + } + + /** + * Bean property setter: <property>attribute</property>. + * + * <p> + * Declares whether the property definition translates to an attribute instead of an element. + * + * <p> + * Default value is <jk>false</jk>. + * + * @param attribute The new value for the <property>attribute</property> property on this bean. + * @return This object (for method chaining). + */ + public Xml setAttribute(Boolean attribute) { + this.attribute = attribute; + return this; + } + + /** + * Synonym for {@link #setAttribute(Boolean)}. + * + * @param attribute The new value for the <property>attribute</property> property on this bean. + * @return This object (for method chaining). + */ + public Xml attribute(Boolean attribute) { + return setAttribute(attribute); + } + + /** + * Bean property getter: <property>wrapped</property>. + * + * <p> + * MAY be used only for an array definition. + * + * <p> + * Signifies whether the array is wrapped (for example, + * <code><books><book/><book/><books></code>) or unwrapped + * (<code><book/><book/></code>). + * Default value is <jk>false</jk>. + * The definition takes effect only when defined alongside <code>type</code> being <code>array</code> + * (outside the <code>items</code>). + * + * @return The value of the <property>wrapped</property> property on this bean, or <jk>null</jk> if it is not set. + */ + public Boolean getWrapped() { + return wrapped; + } + + /** + * Bean property setter: <property>wrapped</property>. + * + * <p> + * MAY be used only for an array definition. + * + * <p> + * Signifies whether the array is wrapped (for example, + * <code><books><book/><book/><books></code>) or unwrapped + * (<code><book/><book/></code>). + * Default value is <jk>false</jk>. + * The definition takes effect only when defined alongside <code>type</code> being <code>array</code> + * (outside the <code>items</code>). + * + * @param wrapped The new value for the <property>wrapped</property> property on this bean. + * @return This object (for method chaining). + */ + public Xml setWrapped(Boolean wrapped) { + this.wrapped = wrapped; + return this; + } + + /** + * Synonym for {@link #setWrapped(Boolean)}. + * + * @param wrapped The new value for the <property>wrapped</property> property on this bean. + * @return This object (for method chaining). + */ + public Xml wrapped(Boolean wrapped) { + return setWrapped(wrapped); + } +} http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/75b0d8ee/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/package.html ---------------------------------------------------------------------- diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/package.html b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/package.html new file mode 100644 index 0000000..8966843 --- /dev/null +++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/package.html @@ -0,0 +1,214 @@ +<!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>"[email protected]"</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>"[email protected]"</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>
