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 static org.apache.juneau.internal.BeanPropertyUtils.*;
import static org.apache.juneau.internal.StringUtils.*;
import java.util.*;
import org.apache.juneau.*;
import org.apache.juneau.annotation.*;
import org.apache.juneau.http.*;
import org.apache.juneau.internal.*;
import org.apache.juneau.json.*;
import org.apache.juneau.utils.*;
/**
* This is the root document object for the API specification.
*
* See Also:
*
* - {@doc 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 static final Comparator PATH_COMPARATOR = new Comparator() {
@Override /* Comparator */
public int compare(String o1, String o2) {
return o1.replace('{', '@').compareTo(o2.replace('{', '@'));
}
};
private String
swagger = "2.0",
host,
basePath;
private Info info;
private ExternalDocumentation externalDocs;
private List schemes;
private List
consumes,
produces;
private List tags;
private List>> security;
private Map definitions;
private Map parameters;
private Map responses;
private Map securityDefinitions;
private Map paths;
/**
* Default constructor.
*/
public Swagger() {}
/**
* Copy constructor.
*
* @param copyFrom The object to copy.
*/
public Swagger(Swagger copyFrom) {
super(copyFrom);
this.swagger = copyFrom.swagger;
this.host = copyFrom.host;
this.basePath = copyFrom.basePath;
this.info = copyFrom.info == null ? null : copyFrom.info.copy();
this.externalDocs = copyFrom.externalDocs == null ? null : copyFrom.externalDocs.copy();
this.schemes = newList(copyFrom.schemes);
this.consumes = newList(copyFrom.consumes);
this.produces = newList(copyFrom.produces);
this.tags = copyFrom.tags == null ? null : new ArrayList();
if (copyFrom.tags != null)
for (Tag t : copyFrom.tags)
this.tags.add(t.copy());
this.security = copyFrom.security == null ? null : new ArrayList>>();
if (copyFrom.security != null)
for (Map> m : copyFrom.security) {
Map> m2 = new LinkedHashMap<>();
for (Map.Entry> e : m.entrySet())
m2.put(e.getKey(), newList(e.getValue()));
this.security.add(m2);
}
// TODO - Definitions are not deep copied, so they should not contain references.
this.definitions = copyFrom.definitions == null ? null : new LinkedHashMap();
if (copyFrom.definitions != null)
for (Map.Entry e : copyFrom.definitions.entrySet())
this.definitions.put(e.getKey(), new ObjectMap(e.getValue()));
this.parameters = copyFrom.parameters == null ? null : new LinkedHashMap();
if (copyFrom.parameters != null)
for (Map.Entry e : copyFrom.parameters.entrySet())
this.parameters.put(e.getKey(), e.getValue().copy());
this.responses = copyFrom.responses == null ? null : new LinkedHashMap();
if (copyFrom.responses != null)
for (Map.Entry e : copyFrom.responses.entrySet())
this.responses.put(e.getKey(), e.getValue().copy());
this.securityDefinitions = copyFrom.securityDefinitions == null ? null : new LinkedHashMap();
if (copyFrom.securityDefinitions != null)
for (Map.Entry e : copyFrom.securityDefinitions.entrySet())
this.securityDefinitions.put(e.getKey(), e.getValue().copy());
this.paths = copyFrom.paths == null ? null : new LinkedHashMap();
if (copyFrom.paths != null)
for (Map.Entry e : copyFrom.paths.entrySet()) {
OperationMap m = new OperationMap();
for (Map.Entry e2 : e.getValue().entrySet())
m.put(e2.getKey(), e2.getValue().copy());
this.paths.put(e.getKey(), m);
}
}
/**
* Make a deep copy of this object.
*
* @return A deep copy of this object.
*/
public Swagger copy() {
return new Swagger(this);
}
/**
* Bean property getter: swagger .
*
*
* Specifies the Swagger Specification version being used.
*
*
* It can be used by the Swagger UI and other clients to interpret the API listing.
*
* @return The property value, or null if it is not set.
*/
public String getSwagger() {
return swagger;
}
/**
* Bean property setter: swagger .
*
*
* Specifies the Swagger Specification version being used.
*
*
* It can be used by the Swagger UI and other clients to interpret the API listing.
*
* @param value
* The new value for this property.
*
Property value is required.
* @return This object (for method chaining).
*/
public Swagger setSwagger(String value) {
swagger = value;
return this;
}
/**
* Same as {@link #setSwagger(String)}.
*
* @param value
* The new value for this property.
*
Non-String values will be converted to String using toString().
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger swagger(Object value) {
return setSwagger(toStringVal(value));
}
/**
* Bean property getter: info .
*
*
* Provides metadata about the API.
*
*
* The metadata can be used by the clients if needed.
*
* @return The property value, or null if it is not set.
*/
public Info getInfo() {
return info;
}
/**
* Bean property setter: info .
*
*
* Provides metadata about the API.
*
*
* The metadata can be used by the clients if needed.
*
* @param value
* The new value for this property.
*
Property value is required.
* @return This object (for method chaining).
*/
public Swagger setInfo(Info value) {
info = value;
return this;
}
/**
* Same as {@link #setInfo(Info)}.
*
* @param value
* The new value for this property.
*
Valid types:
*
* - {@link Info}
*
String - JSON object representation of {@link Info}
* Example:
*
* info("{title:'title',description:'description',...}" );
*
*
*
Property value is required.
* @return This object (for method chaining).
*/
public Swagger info(Object value) {
return setInfo(toType(value, Info.class));
}
/**
* Bean property getter: host .
*
*
* The host (name or IP) serving the API.
*
* @return The property value, or null if it is not set.
*/
public String getHost() {
return host;
}
/**
* Bean property setter: host .
*
*
* The host (name or IP) serving the API.
*
* @param value
* The new value for this property.
*
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 {@doc SwaggerPathTemplating path templating}
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger setHost(String value) {
host = value;
return this;
}
/**
* Same as {@link #setHost(String)}.
*
* @param value
* The new value for this property.
*
Non-String values will be converted to String using toString().
*
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 {@doc SwaggerPathTemplating path templating}
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger host(Object value) {
return setHost(toStringVal(value));
}
/**
* Bean property getter: basePath .
*
*
* The base path on which the API is served, which is relative to the host.
*
* @return The property value, 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.
*
* @param value
* The new value for this property.
*
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 {@doc SwaggerPathTemplating path templating}.
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger setBasePath(String value) {
basePath = value;
return this;
}
/**
* Same as {@link #setBasePath(String)}.
*
* @param value
* The new value for this property.
*
Non-String values will be converted to String using toString().
*
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 {@doc SwaggerPathTemplating path templating}.
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger basePath(Object value) {
return setBasePath(toStringVal(value));
}
/**
* Bean property getter: schemes .
*
*
* The transfer protocol of the API.
*
*
* If the schemes is not included, the default scheme to be used is the one used to access the Swagger
* definition itself.
*
* @return The property value, or null if it is not set.
*/
public List getSchemes() {
return schemes;
}
/**
* Bean property setter: schemes .
*
*
* The transfer protocol of the API.
*
*
* If the schemes is not included, the default scheme to be used is the one used to access the Swagger
* definition itself.
*
* @param value
* The new value for this property.
*
Valid values:
*
* "http"
* "https"
* "ws"
* "wss"
*
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger setSchemes(Collection value) {
schemes = newList(value);
return this;
}
/**
* Adds one or more values to the schemes property.
*
*
* 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 values
* The values to add to this property.
*
Valid values:
*
* "http"
* "https"
* "ws"
* "wss"
*
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger addSchemes(Collection values) {
schemes = addToList(schemes, values);
return this;
}
/**
* Same as {@link #addSchemes(Collection)}.
*
* @param values
* The values to add to this property.
*
Valid types:
*
* Collection<String>
* String - JSON array representation of Collection<String>
* Example:
*
* schemes("['scheme1','scheme2']" );
*
* String - Individual values
* Example:
*
* schemes("scheme1" , "scheme2" );
*
*
* @return This object (for method chaining).
*/
public Swagger schemes(Object...values) {
schemes = addToList(schemes, values, String.class);
return this;
}
/**
* 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.
*
* @return The property value, 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.
*
* @param value
* The new value for this property.
*
Value MUST be as described under {@doc SwaggerMimeTypes}.
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger setConsumes(Collection value) {
consumes = newList(value);
return this;
}
/**
* Adds one or more values to the consumes property.
*
*
* A list of MIME types the operation can consume.
* This overrides the consumes definition at the Swagger Object.
* An empty value MAY be used to clear the global definition.
* Value MUST be as described under {@doc SwaggerMimeTypes}.
*
* @param values
* The values to add to this property.
*
Values MUST be as described under {@doc SwaggerMimeTypes}.
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger addConsumes(Collection values) {
consumes = addToList(consumes, values);
return this;
}
/**
* Adds one or more values to the consumes property.
*
* @param values
* The values to add to this property.
*
Valid types:
*
* - {@link MediaType}
*
Collection<{@link MediaType}|String>
* String - JSON array representation of Collection<{@link MediaType}>
* Example:
*
* consumes("['text/json']" );
*
* String - Individual values
* Example:
*
* consumes("text/json" );
*
*
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger consumes(Object...values) {
consumes = addToList(consumes, values, MediaType.class);
return this;
}
/**
* 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.
*
* @return The property value, 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.
*
* @param value
* The new value for this property.
*
Value MUST be as described under {@doc SwaggerMimeTypes}.
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger setProduces(Collection value) {
produces = newList(value);
return this;
}
/**
* Adds one or more values to the produces property.
*
*
* A list of MIME types the APIs can produce.
*
*
* This is global to all APIs but can be overridden on specific API calls.
*
* @param values
* The values to add to this property.
*
Value MUST be as described under {@doc SwaggerMimeTypes}.
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger addProduces(Collection values) {
produces = addToList(produces, values);
return this;
}
/**
* Adds one or more values to the produces property.
*
* @param values
* The values to add to this property.
*
Valid types:
*
* - {@link MediaType}
*
Collection<{@link MediaType}|String>
* String - JSON array representation of Collection<{@link MediaType}>
* Example:
*
* consumes("['text/json']" );
*
* String - Individual values
* Example:
*
* consumes("text/json" );
*
*
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger produces(Object...values) {
produces = addToList(produces, values, MediaType.class);
return this;
}
/**
* Bean property getter: paths .
*
*
* The available paths and operations for the API.
*
* @return The property value, or null if it is not set.
*/
public Map getPaths() {
return paths;
}
/**
* Shortcut for calling getPaths().get(path);
*
* @param path The path (e.g. "/foo" ).
* @return The operation map for the specified path, or null if it doesn't exist.
*/
public OperationMap getPath(String path) {
return getPaths().get(path);
}
/**
* Shortcut for calling getPaths().get(path).get(operation);
*
* @param path The path (e.g. "/foo" ).
* @param operation The HTTP operation (e.g. "get" ).
* @return The operation for the specified path and operation id, or null if it doesn't exist.
*/
public Operation getOperation(String path, String operation) {
OperationMap om = getPath(path);
if (om == null)
return null;
return om.get(operation);
}
/**
* Shortcut for calling getPaths().get(path).get(operation).getResponse(status);
*
* @param path The path (e.g. "/foo" ).
* @param operation The HTTP operation (e.g. "get" ).
* @param status The HTTP response status (e.g. "200" ).
* @return The operation for the specified path and operation id, or null if it doesn't exist.
*/
public ResponseInfo getResponseInfo(String path, String operation, Object status) {
OperationMap om = getPath(path);
if (om == null)
return null;
Operation op = om.get(operation);
if (op == null)
return null;
return op.getResponse(status);
}
/**
* Bean property setter: paths .
*
*
* The available paths and operations for the API.
*
* @param value
* The new value for this property.
*
Property value is required.
* @return This object (for method chaining).
*/
public Swagger setPaths(Map value) {
paths = newSortedMap(value, PATH_COMPARATOR);
return this;
}
/**
* Adds one or more values to the produces property.
*
*
* A list of MIME types the APIs can produce.
*
*
* This is global to all APIs but can be overridden on specific API calls.
*
* @param values
* The values to add to this property.
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger addPaths(Map values) {
paths = addToSortedMap(paths, values, PATH_COMPARATOR);
return this;
}
/**
* Adds a single value to the paths property.
*
* @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) {
if (paths == null)
paths = new TreeMap<>(PATH_COMPARATOR);
OperationMap p = paths.get(path);
if (p == null) {
p = new OperationMap();
paths.put(path, p);
}
p.put(methodName, operation);
return this;
}
/**
* Adds one or more values to the paths property.
*
* @param values
* The values to add to this property.
*
Valid types:
*
* Map<String,Map<String,{@link Operation}>|String>
* String - JSON object representation of Map<String,Map<String,{@link Operation}>>
* Example:
*
* paths("{'foo':{'get':{operationId:'operationId',...}}}" );
*
*
*
Ignored if null .
* @return This object (for method chaining).
*/
@SuppressWarnings({ "unchecked", "rawtypes" })
public Swagger paths(Object...values) {
if (paths == null)
paths = new TreeMap<>(PATH_COMPARATOR);
paths = addToMap((Map)paths, values, String.class, Map.class, String.class, Operation.class);
return this;
}
/**
* Bean property getter: definitions .
*
*
* An object to hold data types produced and consumed by operations.
*
* @return The property value, 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 value
* The new value for this property.
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger setDefinitions(Map value) {
definitions = newMap(value);
return this;
}
/**
* Adds one or more values to the definitions property.
*
*
* An object to hold data types produced and consumed by operations.
*
* @param values
* The values to add to this property.
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger addDefinitions(Map values) {
definitions = addToMap(definitions, values);
return this;
}
/**
* Adds a single value to the definitions property.
*
* @param name A definition name.
* @param schema The schema that the name defines.
* @return This object (for method chaining).
*/
public Swagger definition(String name, ObjectMap schema) {
definitions = addToMap(definitions, name, schema);
return this;
}
/**
* Adds one or more values to the definitions property.
*
* @param values
* The values to add to this property.
*
Valid types:
*
* Map<String,Map<String,{@link SchemaInfo}>|String>
* String - JSON object representation of Map<String,Map<String,{@link SchemaInfo}>>
* Example:
*
* definitions("{'foo':{'bar':{format:'format',...}}}" );
*
*
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger definitions(Object...values) {
definitions = addToMap(definitions, values, String.class, ObjectMap.class);
return this;
}
/**
* Convenience method for testing whether this Swagger has one or more definitions defined.
*
* @return true if this Swagger has one or more definitions defined.
*/
public boolean hasDefinitions() {
return definitions != null && ! definitions.isEmpty();
}
/**
* 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 property value, 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 value
* The new value for this property.
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger setParameters(Map value) {
parameters = newMap(value);
return this;
}
/**
* Adds one or more values to the parameters property.
*
*
* An object to hold parameters that can be used across operations.
*
*
* This property does not define global parameters for all operations.
*
* @param values
* The values to add to this property.
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger addParameters(Map values) {
parameters = addToMap(parameters, values);
return this;
}
/**
* Adds a single value to the parameter property.
*
* @param name The parameter name.
* @param parameter The parameter definition.
* @return This object (for method chaining).
*/
public Swagger parameter(String name, ParameterInfo parameter) {
parameters = addToMap(parameters, name, parameter);
return this;
}
/**
* Adds one or more values to the properties property.
*
* @param values
* The values to add to this property.
*
Valid types:
*
* Map<String,{@link ParameterInfo}|String>
* String - JSON object representation of Map<String,{@link ParameterInfo}>
* Example:
*
* parameters("{'foo':{name:'name',...}}" );
*
*
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger parameters(Object...values) {
parameters = addToMap(parameters, values, String.class, ParameterInfo.class);
return this;
}
/**
* Convenience method for calling getPath(path).get(method).getParameter(in,name);
*
* @param path The HTTP path.
* @param method The HTTP method.
* @param in The parameter type.
* @param name The parameter name.
* @return The parameter information or null if not found.
*/
public ParameterInfo getParameterInfo(String path, String method, String in, String name) {
OperationMap om = getPath(path);
if (om != null) {
Operation o = om.get(method);
if (o != null) {
return o.getParameter(in, name);
}
}
return null;
}
/**
* 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 property value, 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 value
* The new value for this property.
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger setResponses(Map value) {
responses = newMap(value);
return this;
}
/**
* Adds one or more values to the responses property.
*
*
* An object to hold responses that can be used across operations.
*
*
* This property does not define global responses for all operations.
*
* @param values
* The values to add to this property.
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger addResponses(Map values) {
responses = addToMap(responses, values);
return this;
}
/**
* Adds a single value to the responses property.
*
* @param name The response name.
* @param response The response definition.
* @return This object (for method chaining).
*/
public Swagger response(String name, ResponseInfo response) {
responses = addToMap(responses, name, response);
return this;
}
/**
* Adds one or more values to the properties property.
*
* @param values
* The values to add to this property.
*
Valid types:
*
* Map<String,{@link ResponseInfo}|String>
* String - JSON object representation of Map<String,{@link ResponseInfo}>
* Example:
*
* responses("{'foo':{description:'description',...}}" );
*
*
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger responses(Object...values) {
responses = addToMap(responses, values, String.class, ResponseInfo.class);
return this;
}
/**
* Bean property getter: securityDefinitions .
*
*
* Security scheme definitions that can be used across the specification.
*
* @return The property value, 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 value
* The new value for this property.
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger setSecurityDefinitions(Map value) {
securityDefinitions = newMap(value);
return this;
}
/**
* Adds one or more values to the securityDefinitions property.
*
*
* Security scheme definitions that can be used across the specification.
*
* @param values
* The values to add to this property.
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger addSecurityDefinitions(Map values) {
securityDefinitions = addToMap(securityDefinitions, values);
return this;
}
/**
* Adds a single value to the securityDefinitions property.
*
* @param name A security name.
* @param securityScheme A security schema.
* @return This object (for method chaining).
*/
public Swagger securityDefinition(String name, SecurityScheme securityScheme) {
securityDefinitions = addToMap(securityDefinitions, name, securityScheme);
return this;
}
/**
* Adds one or more values to the securityDefinitions property.
*
* @param values
* The values to add to this property.
*
Valid types:
*
* Map<String,{@link SecurityScheme}|String>
* String - JSON object representation of Map<String,{@link SecurityScheme}>
* Example:
*
* securityDefinitions("{'foo':{name:'name',...}}" );
*
*
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger securityDefinitions(Object...values) {
securityDefinitions = addToMap(securityDefinitions, values, String.class, SecurityScheme.class);
return this;
}
/**
* 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 property value, 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 value
* The new value for this property.
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger setSecurity(Collection>> value) {
security = newList(value);
return this;
}
/**
* Adds one or more values to the security property.
*
*
* 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 values
* The values to add to this property.
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger addSecurity(Collection>> values) {
security = addToList(security, values);
return this;
}
/**
* Adds a single value to the securityDefinitions property.
*
* @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(Collections.singleton(m));
}
/**
* Adds one or more values to the securityDefinitions property.
*
* @param values
* The values to add to this property.
*
Valid types:
*
* Collection<Map<String,List<String>>>
* String - JSON array representation of Collection<Map<String,List<String>>>
* Example:
*
* securities("[{...}]" );
*
* String - JSON object representation of Map<String,List<String>>
* Example:
*
* securities("{...}" );
*
*
*
Ignored if null .
* @return This object (for method chaining).
*/
@SuppressWarnings({ "unchecked", "rawtypes" })
public Swagger securities(Object...values) {
security = addToList((List)security, values, Map.class, String.class, List.class, String.class);
return this;
}
/**
* Bean property getter: tags .
*
*
* A list of tags used by the specification with additional metadata.
*
* @return The property value, 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.
*
* @param value
* The new value for this property.
*
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 {@doc SwaggerOperationObject 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.
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger setTags(Collection value) {
tags = newList(value);
return this;
}
/**
* Adds one or more values to the security property.
*
*
* A list of tags used by the specification with additional metadata.
*
* @param values
* The values to add to this property.
*
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 {@doc SwaggerOperationObject 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.
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger addTags(Collection values) {
tags = addToList(tags, values);
return this;
}
/**
* Adds one or more values to the tags property.
*
* @param values
* The values to add to this property.
*
Valid types:
*
* - {@link Tag}
*
Collection<{@link Tag}|String>
* {@link Tag}[]
* String - JSON array representation of Collection<{@link Tag}>
* Example:
*
* tags("[{name:'name',description:'description',...}]" );
*
* String - JSON object representation of {@link Tag}
* Example:
*
* tags("{name:'name',description:'description',...}" );
*
*
*
Ignored if null .
* @return This object (for method chaining).
*/
public Swagger tags(Object...values) {
tags = addToList(tags, values, Tag.class);
return this;
}
/**
* Convenience method for testing whether this Swagger has one or more tags defined.
*
* @return true if this Swagger has one or more tags defined.
*/
public boolean hasTags() {
return tags != null && ! tags.isEmpty();
}
/**
* Bean property getter: externalDocs .
*
*
* Additional external documentation.
*
* @return The property value, or null if it is not set.
*/
public ExternalDocumentation getExternalDocs() {
return externalDocs;
}
/**
* Bean property setter: externalDocs .
*
*
* Additional external documentation.
*
* @param value
* The new value for this property.
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger setExternalDocs(ExternalDocumentation value) {
externalDocs = value;
return this;
}
/**
* Same as {@link #setExternalDocs(ExternalDocumentation)}.
*
* @param value
* The new value for this property.
*
Valid types:
*
* - {@link ExternalDocumentation}
*
String - JSON object representation of {@link ExternalDocumentation}
* Example:
*
* externalDocs("{description:'description',url:'url'}" );
*
*
*
Can be null to unset the property.
* @return This object (for method chaining).
*/
public Swagger externalDocs(Object value) {
return setExternalDocs(toType(value, ExternalDocumentation.class));
}
@Override /* SwaggerElement */
public T get(String property, Class type) {
if (property == null)
return null;
switch (property) {
case "swagger": return toType(getSwagger(), type);
case "info": return toType(getInfo(), type);
case "host": return toType(getHost(), type);
case "basePath": return toType(getBasePath(), type);
case "schemes": return toType(getSchemes(), type);
case "consumes": return toType(getConsumes(), type);
case "produces": return toType(getProduces(), type);
case "paths": return toType(getPaths(), type);
case "definitions": return toType(getDefinitions(), type);
case "parameters": return toType(getParameters(), type);
case "responses": return toType(getResponses(), type);
case "securityDefinitions": return toType(getSecurityDefinitions(), type);
case "security": return toType(getSecurity(), type);
case "tags": return toType(getTags(), type);
case "externalDocs": return toType(getExternalDocs(), type);
default: return super.get(property, type);
}
}
@Override /* SwaggerElement */
public Swagger set(String property, Object value) {
if (property == null)
return this;
switch (property) {
case "swagger": return swagger(value);
case "info": return info(value);
case "host": return host(value);
case "basePath": return basePath(value);
case "schemes": return setSchemes(null).schemes(value);
case "consumes": return setConsumes(null).consumes(value);
case "produces": return setProduces(null).produces(value);
case "paths": return setPaths(null).paths(value);
case "definitions": return setDefinitions(null).definitions(value);
case "parameters": return setParameters(null).parameters(value);
case "responses": return setResponses(null).responses(value);
case "securityDefinitions": return setSecurityDefinitions(null).securityDefinitions(value);
case "security": return setSecurity(null).securities(value);
case "tags": return setTags(null).tags(value);
case "externalDocs": return externalDocs(value);
default:
super.set(property, value);
return this;
}
}
@Override /* SwaggerElement */
public Set keySet() {
ASet s = new ASet()
.appendIf(swagger != null, "swagger")
.appendIf(info != null, "info")
.appendIf(host != null, "host")
.appendIf(basePath != null, "basePath")
.appendIf(schemes != null, "schemes")
.appendIf(consumes != null, "consumes")
.appendIf(produces != null, "produces")
.appendIf(paths != null, "paths")
.appendIf(definitions != null, "definitions")
.appendIf(parameters != null, "parameters")
.appendIf(responses != null, "responses")
.appendIf(securityDefinitions != null, "securityDefinitions")
.appendIf(security != null, "security")
.appendIf(tags != null, "tags")
.appendIf(externalDocs != null, "externalDocs");
return new MultiSet<>(s, super.keySet());
}
@Override /* Object */
public String toString() {
return JsonSerializer.DEFAULT.toString(this);
}
/**
* Resolves a "$ref" tags to nodes in this swagger document.
*
* @param ref The ref tag value.
* @param c The class to convert the reference to.
* @return The referenced node, or null if the ref was null or empty or not found.
*/
public T findRef(String ref, Class c) {
if (isEmpty(ref))
return null;
if (! ref.startsWith("#/"))
throw new RuntimeException("Unsupported reference: '" + ref + '"');
try {
return new PojoRest(this).get(ref.substring(1), c);
} catch (Exception e) {
throw new BeanRuntimeException(e, c, "Reference ''{0}'' could not be converted to type ''{1}''.", ref, c.getName());
}
}
}