org.apache.juneau.dto.swagger.Swagger Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * 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.json.*;
import org.apache.juneau.utils.*;
/**
* This is the root document object for the API specification.
*
* Additional Information
*
* -
* Juneau Data Transfer Objects
* (org.apache.juneau.dto)
*
* -
* Swagger
*
*
* -
* org.apache.juneau.dto.swagger
*
*
*/
@Bean(properties="swagger,info,tags,externalDocs,basePath,schemes,consumes,produces,paths,definitions,parameters,responses,securityDefinitions,security")
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 schemes;
private List consumes;
private List produces;
private Map> paths;
private Map definitions;
private Map parameters;
private Map responses;
private Map securityDefinitions;
private List>> security;
private List tags;
private ExternalDocumentation externalDocs;
/**
* Bean property getter: swagger .
*
*
* Required. Specifies the Swagger Specification version being used.
*
*
* It can be used by the Swagger UI and other clients to interpret the API listing.
* The value MUST be "2.0" .
*
* @return The value of the swagger property on this bean, or null if it is not set.
*/
public String getSwagger() {
return swagger;
}
/**
* Bean property setter: swagger .
*
*
* Required. Specifies the Swagger Specification version being used.
*
*
* It can be used by the Swagger UI and other clients to interpret the API listing.
* The value MUST be "2.0" .
*
* @param swagger The new value for the swagger 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 swagger property on this bean.
* @return This object (for method chaining).
*/
public Swagger swagger(String swagger) {
return setSwagger(swagger);
}
/**
* Bean property getter: info .
*
*
* Required. Provides metadata about the API.
*
*
* The metadata can be used by the clients if needed.
*
* @return The value of the info property on this bean, or null if it is not set.
*/
public Info getInfo() {
return info;
}
/**
* Bean property setter: info .
*
*
* Required. Provides metadata about the API.
*
*
* The metadata can be used by the clients if needed.
*
* @param info The new value for the info 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 info property on this bean.
* @return This object (for method chaining).
*/
public Swagger info(Info info) {
return setInfo(info);
}
/**
* Bean property getter: host .
*
*
* The host (name or IP) serving the API.
*
*
* 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
* path templating.
*
* @return The value of the host property on this bean, or null if it is not set.
*/
public String getHost() {
return host;
}
/**
* Bean property setter: host .
*
*
* The host (name or IP) serving the API.
*
*
* 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
* path templating.
*
* @param host The new value for the host 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 host property on this bean.
* @return This object (for method chaining).
*/
public Swagger host(String host) {
return setHost(host);
}
/**
* Bean property getter: basePath .
*
*
* The base path on which the API is served, which is relative to the host.
*
*
* If it is not included, the API is served directly under the host.
* The value MUST start with a leading slash (/).
* The basePath does not support path templating.
*
* @return The value of the basePath property on this bean, or null if it is not set.
*/
public String getBasePath() {
return basePath;
}
/**
* Bean property setter: basePath .
*
*
* The base path on which the API is served, which is relative to the host.
*
*
* If it is not included, the API is served directly under the host.
* The value MUST start with a leading slash (/).
* The basePath does not support path templating.
*
* @param basePath The new value for the basePath 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 basePath property on this bean.
* @return This object (for method chaining).
*/
public Swagger basePath(String basePath) {
return setBasePath(basePath);
}
/**
* Bean property getter: schemes .
*
*
* The transfer protocol of the API.
*
*
* Values MUST be from the list: "http" , "https" , "ws" , "wss" .
* If the schemes is not included, the default scheme to be used is the one used to access the Swagger
* definition itself.
*
* @return The value of the schemes property on this bean, or null if it is not set.
*/
public List getSchemes() {
return schemes;
}
/**
* Bean property setter: schemes .
*
*
* The transfer protocol of the API.
*
*
* Values MUST be from the list: "http" , "https" , "ws" , "wss" .
* If the schemes 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 schemes property on this bean.
* @return This object (for method chaining).
*/
public Swagger setSchemes(List schemes) {
this.schemes = schemes;
return this;
}
/**
* Bean property adder: schemes .
*
*
* The transfer protocol of the API.
*
*
* Values MUST be from the list: "http" , "https" , "ws" , "wss" .
* If the schemes 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 schemes property on this bean.
* @return This object (for method chaining).
*/
public Swagger addSchemes(String...schemes) {
return addSchemes(Arrays.asList(schemes));
}
/**
* Bean property adder: schemes .
*
*
* The transfer protocol of the API.
*
*
* Values MUST be from the list: "http" , "https" , "ws" , "wss" .
* If the schemes 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 schemes property on this bean.
* @return This object (for method chaining).
*/
public Swagger addSchemes(Collection schemes) {
if (schemes != null) {
if (this.schemes == null)
this.schemes = new LinkedList();
this.schemes.addAll(schemes);
}
return this;
}
/**
* Synonym for {@link #addSchemes(String...)}.
*
* @param schemes The values to add for the schemes property on this bean.
* @return This object (for method chaining).
*/
public Swagger schemes(String...schemes) {
return addSchemes(schemes);
}
/**
* Bean property getter: consumes .
*
*
* A list of MIME types the APIs can consume.
*
*
* This is global to all APIs but can be overridden on specific API calls.
* Value MUST be as described under
* Mime Types.
*
* @return The value of the consumes property on this bean, or null if it is not set.
*/
public List getConsumes() {
return consumes;
}
/**
* Bean property setter: consumes .
*
*
* A list of MIME types the APIs can consume.
*
*
* This is global to all APIs but can be overridden on specific API calls.
* Value MUST be as described under
* Mime Types.
*
* @param consumes The new value for the consumes property on this bean.
* @return This object (for method chaining).
*/
public Swagger setConsumes(List consumes) {
this.consumes = consumes;
return this;
}
/**
* Bean property adder: consumes .
*
*
* A list of MIME types the APIs can consume.
*
*
* This is global to all APIs but can be overridden on specific API calls.
* Value MUST be as described under
* Mime Types.
*
* @param consumes The values to add for the consumes property on this bean.
* @return This object (for method chaining).
*/
public Swagger addConsumes(MediaType...consumes) {
return addConsumes(Arrays.asList(consumes));
}
/**
* Bean property adder: consumes .
*
*
* A list of MIME types the APIs can consume.
*
*
* This is global to all APIs but can be overridden on specific API calls.
* Value MUST be as described under
* Mime Types.
*
* @param consumes The values to add for the consumes property on this bean.
* @return This object (for method chaining).
*/
public Swagger addConsumes(Collection consumes) {
if (consumes != null) {
if (this.consumes == null)
this.consumes = new LinkedList();
this.consumes.addAll(consumes);
}
return this;
}
/**
* Synonym for {@link #addConsumes(MediaType...)}.
*
* @param consumes The values to add for the consumes 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 consumes property on this bean.
* @return This object (for method chaining).
*/
public Swagger consumes(Collection consumes) {
return addConsumes(consumes);
}
/**
* Bean property getter: produces .
*
*
* A list of MIME types the APIs can produce.
*
*
* This is global to all APIs but can be overridden on specific API calls.
* Value MUST be as described under
* Mime Types.
*
* @return The value of the produces property on this bean, or null if it is not set.
*/
public List getProduces() {
return produces;
}
/**
* Bean property setter: produces .
*
*
* A list of MIME types the APIs can produce.
*
*
* This is global to all APIs but can be overridden on specific API calls.
* Value MUST be as described under
* Mime Types.
*
* @param produces The new value for the produces property on this bean.
* @return This object (for method chaining).
*/
public Swagger setProduces(List produces) {
this.produces = produces;
return this;
}
/**
* Bean property adder: produces .
*
*
* A list of MIME types the APIs can produce.
*
*
* This is global to all APIs but can be overridden on specific API calls.
* Value MUST be as described under
* Mime Types.
*
* @param produces The values to add for the produces property on this bean.
* @return This object (for method chaining).
*/
public Swagger addProduces(MediaType...produces) {
return addProduces(Arrays.asList(produces));
}
/**
* Bean property adder: produces .
*
*
* A list of MIME types the APIs can produce.
*
*
* This is global to all APIs but can be overridden on specific API calls.
* Value MUST be as described under
* Mime Types.
*
* @param produces The values to add for the produces property on this bean.
* @return This object (for method chaining).
*/
public Swagger addProduces(Collection produces) {
if (produces != null) {
if (this.produces == null)
this.produces = new LinkedList();
this.produces.addAll(produces);
}
return this;
}
/**
* Synonym for {@link #addProduces(MediaType...)}.
*
* @param produces The values to add for the produces 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 produces property on this bean.
* @return This object (for method chaining).
*/
public Swagger produces(Collection produces) {
return addProduces(produces);
}
/**
* Bean property getter: paths .
*
*
* Required. The available paths and operations for the API.
*
* @return The value of the paths property on this bean, or null if it is not set.
*/
public Map> getPaths() {
return paths;
}
/**
* Bean property setter: paths .
*
*
* Required. The available paths and operations for the API.
*
* @param paths The new value for the paths property on this bean.
* @return This object (for method chaining).
*/
public Swagger setPaths(Map> paths) {
this.paths = paths;
return this;
}
/**
* Bean property adder: paths .
*
*
* 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>();
Map p = paths.get(path);
if (p == null) {
p = new TreeMap(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: definitions .
*
*
* An object to hold data types produced and consumed by operations.
*
* @return
* The value of the definitions property on this bean, or null if it is not set.
*/
public Map getDefinitions() {
return definitions;
}
/**
* Bean property setter: definitions .
*
*
* An object to hold data types produced and consumed by operations.
*
* @param definitions The new value for the definitions property on this bean.
* @return This object (for method chaining).
*/
public Swagger setDefinitions(Map definitions) {
this.definitions = definitions;
return this;
}
/**
* Bean property adder: definitions .
*
*
* 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();
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: parameters .
*
*
* An object to hold parameters that can be used across operations.
*
*
* This property does not define global parameters for all operations.
*
* @return The value of the parameters property on this bean, or null if it is not set.
*/
public Map getParameters() {
return parameters;
}
/**
* Bean property setter: parameters .
*
*
* An object to hold parameters that can be used across operations.
*
*
* This property does not define global parameters for all operations.
*
* @param parameters The new value for the parameters property on this bean.
* @return This object (for method chaining).
*/
public Swagger setParameters(Map parameters) {
this.parameters = parameters;
return this;
}
/**
* Bean property adder: parameters .
*
*
* An object to hold parameters that can be used across operations.
*
*
* 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();
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: responses .
*
*
* An object to hold responses that can be used across operations.
*
*
* This property does not define global responses for all operations.
*
* @return The value of the responses property on this bean, or null if it is not set.
*/
public Map getResponses() {
return responses;
}
/**
* Bean property setter: responses .
*
*
* An object to hold responses that can be used across operations.
*
*
* This property does not define global responses for all operations.
*
* @param responses The new value for the responses property on this bean.
* @return This object (for method chaining).
*/
public Swagger setResponses(Map responses) {
this.responses = responses;
return this;
}
/**
* Bean property adder: responses .
*
*
* An object to hold responses that can be used across operations.
*
*
* 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();
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: securityDefinitions .
*
*
* Security scheme definitions that can be used across the specification.
*
* @return
* The value of the securityDefinitions property on this bean, or null if it
* is not set.
*/
public Map getSecurityDefinitions() {
return securityDefinitions;
}
/**
* Bean property setter: securityDefinitions .
*
*
* Security scheme definitions that can be used across the specification.
*
* @param securityDefinitions The new value for the securityDefinitions property on this bean.
* @return This object (for method chaining).
*/
public Swagger setSecurityDefinitions(Map securityDefinitions) {
this.securityDefinitions = securityDefinitions;
return this;
}
/**
* Bean property adder: securityDefinitions .
*
*
* 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();
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: security .
*
*
* A declaration of which security schemes are applied for the API as a whole.
*
*
* 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 security property on this bean, or null if it is not set.
*/
public List>> getSecurity() {
return security;
}
/**
* Bean property setter: security .
*
*
* A declaration of which security schemes are applied for the API as a whole.
*
*
* 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 security property on this bean.
* @return This object (for method chaining).
*/
public Swagger setSecurity(List>> security) {
this.security = security;
return this;
}
/**
* Bean property adder: security .
*
*
* A declaration of which security schemes are applied for the API as a whole.
*
*
* 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 security property on this bean.
* @return This object (for method chaining).
*/
public Swagger addSecurity(Map> security) {
if (this.security == null)
this.security = new LinkedList>>();
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> m = new LinkedHashMap>();
m.put(scheme, Arrays.asList(alternatives));
return addSecurity(m);
}
/**
* Bean property getter: tags .
*
*
* A list of tags used by the specification with additional metadata.
*
*
* 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
* Operation Object 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 tags property on this bean, or null if it is not set.
*/
public List getTags() {
return tags;
}
/**
* Bean property setter: tags .
*
*
* A list of tags used by the specification with additional metadata.
*
*
* 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
* Operation Object 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 tags property on this bean.
* @return This object (for method chaining).
*/
public Swagger setTags(List tags) {
this.tags = tags;
return this;
}
/**
* Bean property adder: tags .
*
*
* A list of tags used by the specification with additional metadata.
*
*
* 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
* Operation Object 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 tags property on this bean.
* @return This object (for method chaining).
*/
public Swagger addTags(Tag...tags) {
if (this.tags == null)
this.tags = new LinkedList();
this.tags.addAll(Arrays.asList(tags));
return this;
}
/**
* Synonym for {@link #addTags(Tag...)}.
*
* @param tags The values to add for the tags 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 tags property on this bean.
* @return This object (for method chaining).
*/
public Swagger tags(List tags) {
return setTags(tags);
}
/**
* Bean property getter: externalDocs .
*
*
* Additional external documentation.
*
* @return
* The value of the externalDocs property on this bean, or null if it is
* not set.
*/
public ExternalDocumentation getExternalDocs() {
return externalDocs;
}
/**
* Bean property setter: externalDocs .
*
*
* Additional external documentation.
*
* @param externalDocs The new value for the externalDocs 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 externalDocs property on this bean.
* @return This object (for method chaining).
*/
public Swagger externalDocs(ExternalDocumentation externalDocs) {
return setExternalDocs(externalDocs);
}
private static class MethodSorter implements Comparator {
private final Map methods = new AMap()
.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);
}
}
@Override /* Object */
public String toString() {
return JsonSerializer.DEFAULT.toString(this);
}
}