Package org.apache.juneau.bean.swagger

Class Swagger

java.lang.Object
org.apache.juneau.bean.swagger.SwaggerElement
org.apache.juneau.bean.swagger.Swagger
public class Swagger extends SwaggerElement
This is the root document object for the Swagger 2.0 API specification.

The Swagger Object is the root document that describes an entire API. It contains metadata about the API, available paths and operations, parameters, responses, security definitions, and other information. This is the Swagger 2.0 specification (predecessor to OpenAPI 3.0).

Swagger Specification:

The Swagger Object is composed of the following fields:

  • swagger (string, REQUIRED) - The Swagger Specification version (must be "2.0")
  • info (Info, REQUIRED) - Provides metadata about the API
  • host (string) - The host (name or IP) serving the API
  • basePath (string) - The base path on which the API is served (relative to host)
  • schemes (array of string) - The transfer protocols of the API (e.g., "http", "https")
  • consumes (array of string) - A list of MIME types the APIs can consume
  • produces (array of string) - A list of MIME types the APIs can produce
  • paths (map of OperationMap, REQUIRED) - The available paths and operations for the API
  • definitions (map of SchemaInfo) - Schema definitions that can be referenced
  • parameters (map of ParameterInfo) - Parameters definitions that can be referenced
  • responses (map of ResponseInfo) - Response definitions that can be referenced
  • securityDefinitions (map of SecurityScheme) - Security scheme definitions
  • security (array of map) - Security requirements applied to all operations
  • tags (array of Tag) - A list of tags used by the specification with additional metadata
  • externalDocs (ExternalDocumentation) - Additional external documentation
Example:

// Create a Swagger document Swagger doc = new Swagger() .setSwagger("2.0") .setInfo( new Info() .setTitle("Pet Store API") .setVersion("1.0.0") ) .setHost("petstore.swagger.io") .setBasePath("/v2") .setSchemes("https") .addPath("/pets", "get", new Operation() .setSummary("List all pets") .addResponse("200", new ResponseInfo("Success")) );

See Also:

  • Field Details

    • NULL

      public static final Swagger NULL
      Represents a null swagger

  • Constructor Details

    • Swagger

      public Swagger()
      Default constructor.

    • Swagger

      public Swagger(Swagger copyFrom)
      Copy constructor.
      Parameters:
      copyFrom - The object to copy.

  • Method Details

    • copy

      public Swagger copy()
      Make a deep copy of this object.
      Returns:
      A deep copy of this object.

    • getBasePath

      public String getBasePath()
      Bean property getter: basePath.

      The base path on which the API is served, which is relative to the host.

      Returns:
      The property value, or null if it is not set.

    • setBasePath

      public Swagger setBasePath(String value)
      Bean property setter: basePath.

      The base path on which the API is served, which is relative to the host.

      Parameters:
      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 path templating.
      Can be null to unset the property.
      Returns:
      This object.

    • getConsumes

      public Set<MediaType> getConsumes()
      Bean property getter: consumes.

      A list of MIME types the APIs can consume.

      Returns:
      The property value, or null if it is not set.

    • setConsumes

      public Swagger setConsumes(Collection<MediaType> value)
      Bean property setter: consumes.

      A list of MIME types the APIs can consume.

      Parameters:
      value - The new value for this property.
      Value MUST be as described under Swagger Mime Types.
      Can be null to unset the property.
      Returns:
      This object.

    • addConsumes

      public Swagger addConsumes(MediaType... values)
      Bean property appender: consumes.

      A list of MIME types the APIs can consume.

      Parameters:
      values - The values to add to this property.
      Values MUST be as described under Swagger Mime Types.
      Ignored if null.
      Returns:
      This object.

    • addConsumes

      public Swagger addConsumes(Collection<MediaType> values)
      Bean property appender: consumes.

      A list of MIME types the APIs can consume.

      Parameters:
      values - The values to add to this property.
      Ignored if null.
      Returns:
      This object.

    • setConsumes

      public Swagger setConsumes(MediaType... value)
      Bean property fluent setter: consumes.

      A list of MIME types the APIs can consume.

      Parameters:
      value - The values to set on this property.
      Returns:
      This object.

    • getDefinitions

      public Map<String,JsonMap> getDefinitions()
      Bean property getter: definitions.

      An object to hold data types produced and consumed by operations.

      Returns:
      The property value, or null if it is not set.

    • setDefinitions

      public Swagger setDefinitions(Map<String,JsonMap> value)
      Bean property setter: definitions.

      An object to hold data types produced and consumed by operations.

      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • addDefinition

      public Swagger addDefinition(String name, JsonMap schema)
      Bean property appender: definitions.

      Adds a single value to the definitions property.

      Parameters:
      name - A definition name. Must not be null.
      schema - The schema that the name defines. Must not be null.
      Returns:
      This object.

    • getExternalDocs

      public ExternalDocumentation getExternalDocs()
      Bean property getter: externalDocs.

      Additional external documentation.

      Returns:
      The property value, or null if it is not set.

    • setExternalDocs

      public Swagger setExternalDocs(ExternalDocumentation value)
      Bean property setter: externalDocs.

      Additional external documentation.

      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • getHost

      public String getHost()
      Bean property getter: host.

      The host (name or IP) serving the API.

      Returns:
      The property value, or null if it is not set.

    • setHost

      public Swagger setHost(String value)
      Bean property setter: host.

      The host (name or IP) serving the API.

      Parameters:
      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 path templating
      Can be null to unset the property.
      Returns:
      This object.

    • getInfo

      public Info getInfo()
      Bean property getter: info.

      Provides metadata about the API.

      Returns:
      The property value, or null if it is not set.

    • setInfo

      public Swagger setInfo(Info value)
      Bean property setter: info.

      Provides metadata about the API.

      Parameters:
      value - The new value for this property.
      Property value is required.
      Can be null to unset the property.
      Returns:
      This object.

    • getParameters

      public Map<String,ParameterInfo> getParameters()
      Bean property getter: parameters.

      An object to hold parameters that can be used across operations.

      Returns:
      The property value, or null if it is not set.

    • setParameters

      public Swagger setParameters(Map<String,ParameterInfo> value)
      Bean property setter: parameters.

      An object to hold parameters that can be used across operations.

      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • addParameter

      public Swagger addParameter(String name, ParameterInfo parameter)
      Bean property appender: parameters.

      Adds a single value to the parameter property.

      Parameters:
      name - The parameter name. Must not be null.
      parameter - The parameter definition. Must not be null.
      Returns:
      This object.

    • getPaths

      public Map<String,OperationMap> getPaths()
      Bean property getter: paths.

      The available paths and operations for the API.

      Returns:
      The property value, or null if it is not set.

    • setPaths

      public Swagger setPaths(Map<String,OperationMap> value)
      Bean property setter: paths.

      The available paths and operations for the API.

      Parameters:
      value - The new value for this property.
      Property value is required.
      Can be null to unset the property.
      Returns:
      This object.

    • addPath

      public Swagger addPath(String path, String methodName, Operation operation)
      Bean property appender: paths.

      Adds a single value to the paths property.

      Parameters:
      path - The path template. Must not be null.
      methodName - The HTTP method name. Must not be null.
      operation - The operation that describes the path. Must not be null.
      Returns:
      This object.

    • getProduces

      public Set<MediaType> getProduces()
      Bean property getter: produces.

      A list of MIME types the APIs can produce.

      Returns:
      The property value, or null if it is not set.

    • setProduces

      public Swagger setProduces(Collection<MediaType> value)
      Bean property setter: produces.

      A list of MIME types the APIs can produce.

      Parameters:
      value - The new value for this property.
      Value MUST be as described under Swagger Mime Types.
      Can be null to unset the property.
      Returns:
      This object.

    • addProduces

      public Swagger addProduces(MediaType... values)
      Adds one or more values to the produces property.

      A list of MIME types the APIs can produce.

      Parameters:
      values - The values to add to this property.
      Value MUST be as described under Swagger Mime Types.
      Can be null to unset the property.
      Returns:
      This object.

    • addProduces

      public Swagger addProduces(Collection<MediaType> values)
      Bean property appender: produces.

      A list of MIME types the APIs can produce.

      Parameters:
      values - The values to add to this property.
      Value MUST be as described under Swagger Mime Types.
      Ignored if null.
      Returns:
      This object.

    • setProduces

      public Swagger setProduces(MediaType... value)
      Bean property fluent setter: produces.

      A list of MIME types the APIs can produce.

      Parameters:
      value - The new value for this property.
      Returns:
      This object.

    • getResponses

      public Map<String,ResponseInfo> getResponses()
      Bean property getter: responses.

      An object to hold responses that can be used across operations.

      Returns:
      The property value, or null if it is not set.

    • setResponses

      public Swagger setResponses(Map<String,ResponseInfo> value)
      Bean property setter: responses.

      An object to hold responses that can be used across operations.

      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • addResponse

      public Swagger addResponse(String name, ResponseInfo response)
      Bean property appender: responses.

      Adds a single value to the responses property.

      Parameters:
      name - The response name. Must not be null.
      response - The response definition. Must not be null.
      Returns:
      This object.

    • getSchemes

      public Set<String> getSchemes()
      Bean property getter: schemes.

      The transfer protocol of the API.

      Returns:
      The property value, or null if it is not set.

    • setSchemes

      public Swagger setSchemes(Collection<String> value)
      Bean property setter: schemes.

      The transfer protocol of the API.

      Parameters:
      value - The new value for this property.
      Valid values:
      • "http"
      • "https"
      • "ws"
      • "wss"

      Can be null to unset the property.
      Returns:
      This object.

    • addSchemes

      public Swagger addSchemes(String... values)
      Bean property appender: schemes.

      The transfer protocol of the API.

      Parameters:
      values - The values to add to this property.
      Valid values:
      • "http"
      • "https"
      • "ws"
      • "wss"

      Ignored if null.
      Returns:
      This object.

    • addSchemes

      public Swagger addSchemes(Collection<String> values)
      Bean property appender: schemes.

      The transfer protocol of the API.

      Parameters:
      values - The values to add to this property.
      Valid values:
      • "http"
      • "https"
      • "ws"
      • "wss"

      Ignored if null.
      Returns:
      This object.

    • setSchemes

      public Swagger setSchemes(String... value)
      Bean property fluent setter: schemes.

      The transfer protocol of the API.

      Parameters:
      value - The new value for this property.
      Strings can be JSON arrays.
      Returns:
      This object.

    • getSecurity

      public List<Map<String,List<String>>> getSecurity()
      Bean property getter: security.

      A declaration of which security schemes are applied for the API as a whole.

      Returns:
      The property value, or null if it is not set.

    • setSecurity

      public Swagger setSecurity(Collection<Map<String,List<String>>> value)
      Bean property setter: security.

      A declaration of which security schemes are applied for the API as a whole.

      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • addSecurity

      public Swagger addSecurity(String scheme, String... alternatives)
      Bean property appender: security.

      Adds a single value to the securityDefinitions property.

      Parameters:
      scheme - The security scheme that applies to this operation Must not be null.
      alternatives - The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements).
      Returns:
      This object.

    • addSecurity

      public Swagger addSecurity(Collection<Map<String,List<String>>> values)
      Bean property fluent setter: security.

      A declaration of which security schemes are applied for the API as a whole.

      Parameters:
      values - The values to add to this property.
      Ignored if null.
      Returns:
      This object.

    • getSecurityDefinitions

      public Map<String,SecurityScheme> getSecurityDefinitions()
      Bean property getter: securityDefinitions.

      Security scheme definitions that can be used across the specification.

      Returns:
      The property value, or null if it is not set.

    • setSecurityDefinitions

      public Swagger setSecurityDefinitions(Map<String,SecurityScheme> value)
      Bean property setter: securityDefinitions.

      Security scheme definitions that can be used across the specification.

      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • addSecurityDefinition

      public Swagger addSecurityDefinition(String name, SecurityScheme securityScheme)
      Bean property appender: securityDefinitions.

      Adds a single value to the securityDefinitions property.

      Parameters:
      name - A security name. Must not be null.
      securityScheme - A security schema. Must not be null.
      Returns:
      This object.

    • getSwagger

      public String getSwagger()
      Bean property getter: swagger.

      Specifies the Swagger Specification version being used.

      Returns:
      The property value, or null if it is not set.

    • setSwagger

      public Swagger setSwagger(String value)
      Bean property setter: swagger.

      Specifies the Swagger Specification version being used.

      Parameters:
      value - The new value for this property.
      Property value is required.
      Can be null to unset the property.
      Returns:
      This object.

    • getTags

      public Set<Tag> getTags()
      Bean property getter: tags.

      A list of tags used by the specification with additional metadata.

      Returns:
      The property value, or null if it is not set.

    • setTags

      public Swagger setTags(Collection<Tag> value)
      Bean property setter: tags.

      A list of tags used by the specification with additional metadata.

      Parameters:
      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 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.
      Returns:
      This object.

    • setTags

      public Swagger setTags(Tag... value)
      Bean property setter: tags.

      A list of tags used by the specification with additional metadata.

      Parameters:
      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 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.
      Returns:
      This object.

    • addTags

      public Swagger addTags(Tag... values)
      Bean property appender: tags.

      A list of tags used by the specification with additional metadata.

      Parameters:
      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 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.
      Returns:
      This object.

    • addTags

      public Swagger addTags(Collection<Tag> values)
      Bean property appender: tags.

      A list of tags used by the specification with additional metadata.

      Parameters:
      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 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.
      Returns:
      This object.

    • getPath

      public OperationMap getPath(String path)
      Shortcut for calling getPaths().get(path);
      Parameters:
      path - The path (e.g. "/foo"). Must not be null.
      Returns:
      The operation map for the specified path, or null if it doesn't exist.

    • getOperation

      public Operation getOperation(String path, String operation)
      Shortcut for calling getPaths().get(path).get(operation);
      Parameters:
      path - The path (e.g. "/foo"). Must not be null.
      operation - The HTTP operation (e.g. "get"). Must not be null.
      Returns:
      The operation for the specified path and operation id, or null if it doesn't exist.

    • getResponseInfo

      public ResponseInfo getResponseInfo(String path, String operation, String status)
      Shortcut for calling getPaths().get(path).get(operation).getResponse(status);
      Parameters:
      path - The path (e.g. "/foo"). Must not be null.
      operation - The HTTP operation (e.g. "get"). Must not be null.
      status - The HTTP response status (e.g. "200"). Must not be null.
      Returns:
      The operation for the specified path and operation id, or null if it doesn't exist.

    • getResponseInfo

      public ResponseInfo getResponseInfo(String path, String operation, int status)
      Shortcut for calling getPaths().get(path).get(operation).getResponse(status);
      Parameters:
      path - The path (e.g. "/foo").
      operation - The HTTP operation (e.g. "get").
      status - The HTTP response status (e.g. "200").
      Returns:
      The operation for the specified path and operation id, or null if it doesn't exist.

    • getParameterInfo

      public ParameterInfo getParameterInfo(String path, String method, String in, String name)
      Convenience method for calling getPath(path).get(method).getParameter(in,name);
      Parameters:
      path - The HTTP path. Must not be null.
      method - The HTTP method. Must not be null.
      in - The parameter type. Must not be null.
      name - The parameter name. Can be null for parameter type body.
      Returns:
      The parameter information or null if not found.

    • get

      public <T> T get(String property, Class<T> type)
      Description copied from class: SwaggerElement
      Generic property getter.

      Can be used to retrieve non-standard Swagger fields such as "$ref".

      Overrides:
      get in class SwaggerElement
      Type Parameters:
      T - The datatype to cast the value to.
      Parameters:
      property - The property name to retrieve.
      type - The datatype to cast the value to.
      Returns:
      The property value, or null if the property does not exist or is not set.

    • set

      public Swagger set(String property, Object value)
      Description copied from class: SwaggerElement
      Generic property setter.

      Can be used to set non-standard Swagger fields such as "$ref".

      Overrides:
      set in class SwaggerElement
      Parameters:
      property - The property name to set. Must not be null.
      value - The new value for the property.
      Returns:
      This object.

    • keySet

      public Set<String> keySet()
      Description copied from class: SwaggerElement
      Returns all the keys on this element.
      Overrides:
      keySet in class SwaggerElement
      Returns:
      All the keys on this element.
      Never null.

    • asJson

      public String asJson()
      A synonym of toString().
      Returns:
      This object serialized as JSON.

    • toString

      public String toString()
      Overrides:
      toString in class SwaggerElement

    • findRef

      public <T> T findRef(String ref, Class<T> c)
      Resolves a "$ref" tags to nodes in this swagger document.
      Type Parameters:
      T - The class to convert the reference to.
      Parameters:
      ref - The ref tag value. Must not be null or blank.
      c - The class to convert the reference to. Must not be null.
      Returns:
      The referenced node, or null if not found.

    • strict

      public Swagger strict()
      Sets strict mode on this bean.
      Overrides:
      strict in class SwaggerElement
      Returns:
      This object.

    • strict

      public Swagger strict(Object value)
      Sets strict mode on this bean.
      Overrides:
      strict in class SwaggerElement
      Parameters:
      value - The new value for this property.
      Non-boolean values will be converted to boolean using Boolean.valueOf(value.toString()).
      Can be null (interpreted as false).
      Returns:
      This object.