Package org.apache.juneau.bean.swagger

Class Operation

java.lang.Object
org.apache.juneau.bean.swagger.SwaggerElement
org.apache.juneau.bean.swagger.Operation
public class Operation extends SwaggerElement
Describes a single API operation on a path.

The Operation Object describes a single operation (such as GET, POST, PUT, DELETE) that can be performed on a path in Swagger 2.0. Operations define what actions can be taken, what parameters they accept, what they consume/produce, and what responses they return.

Swagger Specification:

The Operation Object is composed of the following fields:

  • tags (array of string) - A list of tags for API documentation control
  • summary (string) - A short summary of what the operation does
  • description (string) - A verbose explanation of the operation behavior
  • externalDocs (ExternalDocumentation) - Additional external documentation for this operation
  • operationId (string) - Unique string used to identify the operation
  • consumes (array of string) - A list of MIME types the operation can consume
  • produces (array of string) - A list of MIME types the operation can produce
  • parameters (array of ParameterInfo) - A list of parameters that are applicable for this operation
  • responses (map of ResponseInfo, REQUIRED) - The list of possible responses as they are returned from executing this operation
  • schemes (array of string) - The transfer protocol for the operation (overrides the Swagger-level schemes)
  • deprecated (boolean) - Declares this operation to be deprecated
  • security (array of map) - A declaration of which security schemes are applied for this operation
Example:

// Construct using SwaggerBuilder. Operation operation = operation() .tags("pet") .summary("Updates a pet in the store with form data") .description("") .operationId("updatePetWithForm") .consumes("application/x-www-form-urlencoded") .produces("application/json", "application/xml") .parameters( parameter() .name("petId") .in("path") .description("ID of pet that needs to be updated") .required(true) .type("string"), parameter() .name("name") .in("formData") .description("Updated name of the pet") .required(false) .type("string"), parameter() .name("status") .in("formData") .description("Updated status of the pet") .required(false) .type("string") ) .response(200, responseInfo("Pet updated.")) .response(405, responseInfo("Invalid input.")) .security("petstore_auth", "write:pets", "read:pets"); // Serialize using JsonSerializer. String json = Json.from(operation); // Or just use toString() which does the same as above. json = operation.toString();

// Output { "tags": [ "pet" ], "summary": "Updates a pet in the store with form data", "description": "", "operationId": "updatePetWithForm", "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json", "application/xml" ], "parameters": [ { "name": "petId", "in": "path", "description": "ID of pet that needs to be updated", "required": true, "type": "string" }, { "name": "name", "in": "formData", "description": "Updated name of the pet", "required": false, "type": "string" }, { "name": "status", "in": "formData", "description": "Updated status of the pet", "required": false, "type": "string" } ], "responses": { "200": { "description": "Pet updated." }, "405": { "description": "Invalid input" } }, "security": [ { "petstore_auth": [ "write:pets", "read:pets" ] } ] }

See Also:

  • Constructor Details

    • Operation

      public Operation()
      Default constructor.

    • Operation

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

  • Method Details

    • copy

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

    • getConsumes

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

      A list of MIME types the operation can consume.

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

    • setConsumes

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

      A list of MIME types the operation can consume.

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

    • setConsumes

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

      A list of MIME types the operation can consume.

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

    • addConsumes

      public Operation addConsumes(MediaType... value)
      Bean property fluent setter: consumes.

      A list of MIME types the operation can consume.

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

    • addConsumes

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

      A list of MIME types the operation can consume.

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

    • getDeprecated

      public Boolean getDeprecated()
      Bean property getter: deprecated.

      Declares this operation to be deprecated.

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

    • isDeprecated

      public boolean isDeprecated()
      Bean property getter: deprecated.

      Declares this operation to be deprecated.

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

    • setDeprecated

      public Operation setDeprecated(Boolean value)
      Bean property setter: deprecated.

      Declares this operation to be deprecated.

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

    • getDescription

      public String getDescription()
      Bean property getter: description.

      A verbose explanation of the operation behavior.

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

    • setDescription

      public Operation setDescription(String value)
      Bean property setter: description.

      A verbose explanation of the operation behavior.

      Parameters:
      value - The new value for this property.
      GFM syntax can be used for rich text representation.
      Can be null to unset the property.
      Returns:
      This object.

    • getExternalDocs

      public ExternalDocumentation getExternalDocs()
      Bean property getter: externalDocs.

      Additional external documentation for this operation.

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

    • setExternalDocs

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

      Additional external documentation for this operation.

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

    • getOperationId

      public String getOperationId()
      Bean property getter: operationId.

      Unique string used to identify the operation.

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

    • setOperationId

      public Operation setOperationId(String value)
      Bean property setter: operationId.

      Unique string used to identify the operation.

      Parameters:
      value - The new value for this property.
      The id MUST be unique among all operations described in the API.
      Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.
      Can be null to unset the property.
      Returns:
      This object.

    • getParameters

      public List<ParameterInfo> getParameters()
      Bean property getter: parameters.

      A list of parameters that are applicable for this operation.

      Notes:
      • If a parameter is already defined at the Path Item, the new definition will override it, but can never remove it.
      • The list MUST NOT include duplicated parameters.
      • A unique parameter is defined by a combination of a name and location.
      • The list can use the Swagger Reference Object to link to parameters that are defined at the Swagger Object's parameters.
      • There can be one "body" parameter at most.
      Returns:
      The property value, or null if it is not set.

    • getParameter

      public ParameterInfo getParameter(String in, String name)
      Returns the parameter with the specified type and name.
      Parameters:
      in - The parameter in. Must not be null.
      name - The parameter name. Can be null for parameter type body.
      Returns:
      The matching parameter info, or null if not found.

    • setParameters

      public Operation setParameters(Collection<ParameterInfo> value)
      Bean property setter: parameters.

      A list of parameters that are applicable for this operation.

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

    • setParameters

      public Operation setParameters(ParameterInfo... value)
      Bean property setter: parameters.

      A list of parameters that are applicable for this operation.

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

    • addParameters

      public Operation addParameters(ParameterInfo... value)
      Bean property fluent setter: parameters.

      A list of parameters that are applicable for this operation.

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

    • addParameters

      public Operation addParameters(Collection<ParameterInfo> values)
      Bean property fluent setter: parameters.

      The parameters needed to send a valid API call.

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

    • getProduces

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

      A list of MIME types the operation can produce.

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

    • setProduces

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

      A list of MIME types the operation 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.

    • setProduces

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

      A list of MIME types the operation 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 Operation addProduces(MediaType... value)
      Bean property fluent setter: produces.

      A list of MIME types the operation can produce.

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

    • addProduces

      public Operation addProduces(Collection<MediaType> values)
      Bean property setter: produces.

      A list of MIME types the operation can produce.

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

    • getResponses

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

      The list of possible responses as they are returned from executing this operation.

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

    • getResponse

      public ResponseInfo getResponse(String status)
      Returns the response info with the given status code.
      Parameters:
      status - The HTTP status code. Must not be null.
      Returns:
      The response info, or null if not found.

    • getResponse

      public ResponseInfo getResponse(int status)
      Returns the response info with the given status code.
      Parameters:
      status - The HTTP status code.
      Returns:
      The response info, or null if not found.

    • setResponses

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

      The list of possible responses as they are returned from executing this operation.

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

    • addResponse

      public Operation addResponse(String statusCode, ResponseInfo response)
      Adds a single value to the responses property.
      Parameters:
      statusCode - The HTTP status code. Must not be null.
      response - The response description. Must not be null.
      Returns:
      This object.

    • getSchemes

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

      The transfer protocol for the operation.

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

    • setSchemes

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

      The transfer protocol for the operation.

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

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

    • setSchemes

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

      The transfer protocol for the operation.

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

    • addSchemes

      public Operation addSchemes(String... value)
      Bean property fluent setter: schemes.

      The transfer protocol for the operation.

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

    • addSchemes

      public Operation addSchemes(Collection<String> values)
      Bean property setter: schemes.

      The transfer protocol for the operation.

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

    • getSecurity

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

      A declaration of which security schemes are applied for this operation.

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

    • setSecurity

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

      A declaration of which security schemes are applied for this operation.

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

    • setSecurity

      @SafeVarargs public final Operation setSecurity(Map<String,List<String>>... value)
      Bean property setter: security.

      A declaration of which security schemes are applied for this operation.

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

    • addSecurity

      public Operation addSecurity(String scheme, String... alternatives)
      Same as addSecurity(String, String...).
      Parameters:
      scheme - The scheme name.
      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 Operation addSecurity(Collection<Map<String,List<String>>> value)
      Bean property adder: security.

      A declaration of which security schemes are applied for this operation.

      Parameters:
      value - The values to add to this property.
      Must not be null.
      Returns:
      This object.

    • getSummary

      public String getSummary()
      Bean property getter: summary.

      A short summary of what the operation does.

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

    • setSummary

      public Operation setSummary(String value)
      Bean property setter: summary.

      A short summary of what the operation does.

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

    • getTags

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

      A list of tags for API documentation control.
      Tags can be used for logical grouping of operations by resources or any other qualifier.

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

    • setTags

      public Operation setTags(Collection<String> value)
      Bean property setter: tags.

      A list of tags for API documentation control.
      Tags can be used for logical grouping of operations by resources or any other qualifier.

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

    • setTags

      public Operation setTags(String... value)
      Bean property fluent setter: tags.

      A list of tags for API documentation control.
      Tags can be used for logical grouping of operations by resources or any other qualifier.

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

    • addTags

      public Operation addTags(String... value)
      Bean property fluent adder: tags.

      A list of tags for API documentation control.
      Tags can be used for logical grouping of operations by resources or any other qualifier.

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

    • addTags

      public Operation addTags(Collection<String> values)
      Bean property appender: tags.

      A list of tags for API documentation control.

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

    • 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 Operation 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.

    • strict

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

    • strict

      public Operation 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.