Package org.apache.juneau.bean.swagger

Class ParameterInfo

java.lang.Object
org.apache.juneau.bean.swagger.SwaggerElement
org.apache.juneau.bean.swagger.ParameterInfo
public class ParameterInfo extends SwaggerElement
Describes a single operation parameter.

The Parameter Object describes a single parameter used in a Swagger 2.0 API operation. A unique parameter is defined by a combination of a name and location (in). Parameters can be passed in various locations including the path, query string, headers, body, or form data.

Swagger Specification:

The Parameter Object supports the following fields:

  • name (string, REQUIRED) - The name of the parameter
  • in (string, REQUIRED) - The location of the parameter. Possible values: "path", "query", "header", "body", or "formData"
  • description (string) - A brief description of the parameter
  • required (boolean) - Determines whether this parameter is mandatory (must be true if in is "path")
  • schema (SchemaInfo) - The schema defining the type used for the body parameter (only if in is "body")
  • type (string) - The type of the parameter (for non-body parameters). Values: "string", "number", "integer", "boolean", "array", "file"
  • format (string) - The format modifier (e.g., "int32", "int64", "float", "double", "date", "date-time")
  • allowEmptyValue (boolean) - Sets the ability to pass empty-valued parameters (valid only for "query" or "formData" parameters)
  • items (Items) - Required if type is "array". Describes the type of items in the array
  • collectionFormat (string) - How multiple values are formatted. Values: "csv", "ssv", "tsv", "pipes", "multi"
  • default (any) - The default value
  • maximum (number), exclusiveMaximum (boolean), minimum (number), exclusiveMinimum (boolean) - Numeric constraints
  • maxLength (integer), minLength (integer), pattern (string) - String constraints
  • maxItems (integer), minItems (integer), uniqueItems (boolean) - Array constraints
  • enum (array) - Possible values for this parameter
  • multipleOf (number) - Must be a multiple of this value

There are five possible parameter types (determined by the in field):

  • "path" - Used together with Path Templating, where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
  • "query" - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
  • "header" - Custom headers that are expected as part of the request.
  • "body" - The payload that's appended to the HTTP request. Since there can only be one payload, there can only be one body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation.
  • "formData" - Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded, multipart/form-data or both are used as the content type of the request (in Swagger's definition, the consumes property of an operation). This is the only parameter type that can be used to send files, thus supporting the file type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):
    • "application/x-www-form-urlencoded" - Similar to the format of Query parameters but as a payload. For example, foo=1&bar=swagger - both foo and bar are form parameters. This is normally used for simple parameters that are being transferred.
    • "multipart/form-data" - each parameter takes a section in the payload with an internal header. For example, for the header Content-Disposition: form-data; name="submit-name" the name of the parameter is submit-name. This type of form parameters is more commonly used for file transfers.
Example:

// Construct using SwaggerBuilder. ParameterInfo info = parameterInfo("query", "foo"); // Serialize using JsonSerializer. String json = Json.from(info); // Or just use toString() which does the same as above. json = info.toString();

// Output { "in": "query", "name": "foo" }

See Also:

  • Constructor Details

  • Method Details

    • copy

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

    • strict

      public ParameterInfo strict()
      Description copied from class: SwaggerElement
      Sets strict mode on this bean.
      Overrides:
      strict in class SwaggerElement
      Returns:
      This object.

    • strict

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

    • copyFrom

      public ParameterInfo copyFrom(ParameterInfo p)
      Copies any non-null fields from the specified object to this object.
      Parameters:
      p - The object to copy fields from.
      Can be null.
      Returns:
      This object.

    • getAllowEmptyValue

      public Boolean getAllowEmptyValue()
      Bean property getter: allowEmptyValue.

      Sets the ability to pass empty-valued parameters.

      This is valid only for either query or formData parameters and allows you to send a parameter with a name only or an empty value.

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

    • setAllowEmptyValue

      public ParameterInfo setAllowEmptyValue(Boolean value)
      Bean property setter: allowEmptyValue.

      Sets the ability to pass empty-valued parameters.

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

    • getCollectionFormat

      public String getCollectionFormat()
      Bean property getter: collectionFormat.

      Determines the format of the array if type array is used.

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

    • setCollectionFormat

      public ParameterInfo setCollectionFormat(String value)
      Bean property setter: collectionFormat.

      Determines the format of the array if type array is used.

      Parameters:
      value - The new value for this property.
      Valid values:
      • "csv" (default) - comma separated values foo,bar.
      • "ssv" - space separated values foo bar.
      • "tsv" - tab separated values foo\tbar.
      • "pipes" - pipe separated values foo|bar.
      • "multi" - corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz.
        This is valid only for parameters in "query" or "formData".

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

    • getDefault

      public Object getDefault()
      Bean property getter: default.

      Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: "default" has no meaning for required parameters.) Unlike JSON Schema this value MUST conform to the defined type for this parameter.

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

    • setDefault

      public ParameterInfo setDefault(Object value)
      Bean property setter: default.

      Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: "default" has no meaning for required parameters.) Unlike JSON Schema this value MUST conform to the defined type for this parameter.

      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 brief description of the parameter.

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

    • setDescription

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

      A brief description of the parameter.

      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.

    • getEnum

      public Set<Object> getEnum()
      Bean property getter: enum.
      Returns:
      The property value, or null if it is not set.

    • setEnum

      public ParameterInfo setEnum(Collection<Object> value)
      Bean property setter: enum.
      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • addEnum

      public ParameterInfo addEnum(Object... value)
      Bean property appender: enum.
      Parameters:
      value - The values to add to this property.
      Ignored if null.
      Returns:
      This object.

    • setEnum

      public ParameterInfo setEnum(Object... value)
      Bean property fluent setter: enum.
      Parameters:
      value - The new value for this property.
      Strings can be JSON arrays.
      Returns:
      This object.

    • getExclusiveMaximum

      public Boolean getExclusiveMaximum()
      Bean property getter: exclusiveMaximum.
      Returns:
      The property value, or null if it is not set.

    • setExclusiveMaximum

      public ParameterInfo setExclusiveMaximum(Boolean value)
      Bean property setter: exclusiveMaximum.
      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • getExclusiveMinimum

      public Boolean getExclusiveMinimum()
      Bean property getter: exclusiveMinimum.
      Returns:
      The property value, or null if it is not set.

    • setExclusiveMinimum

      public ParameterInfo setExclusiveMinimum(Boolean value)
      Bean property setter: exclusiveMinimum.
      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • getFormat

      public String getFormat()
      Bean property getter: format.

      The extending format for the previously mentioned type.

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

    • setFormat

      public ParameterInfo setFormat(String value)
      Bean property setter: format.

      The extending format for the previously mentioned type.

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

    • getIn

      public String getIn()
      Bean property getter: in.

      The location of the parameter.

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

    • setIn

      public ParameterInfo setIn(String value)
      Bean property setter: in.

      The location of the parameter.

      Parameters:
      value - The new value for this property.
      Valid values:
      • "query"
      • "header"
      • "path"
      • "formData"
      • "body"

      Property value is required.
      Can be null to unset the property.
      Returns:
      This object.

    • getItems

      public Items getItems()
      Bean property getter: items.

      Describes the type of items in the array.

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

    • setItems

      public ParameterInfo setItems(Items value)
      Bean property setter: items.

      Describes the type of items in the array.

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

    • getMaximum

      public Number getMaximum()
      Bean property getter: maximum.
      Returns:
      The property value, or null if it is not set.

    • setMaximum

      public ParameterInfo setMaximum(Number value)
      Bean property setter: maximum.
      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • getMaxItems

      public Integer getMaxItems()
      Bean property getter: maxItems.
      Returns:
      The property value, or null if it is not set.

    • setMaxItems

      public ParameterInfo setMaxItems(Integer value)
      Bean property setter: maxItems.
      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • getMaxLength

      public Integer getMaxLength()
      Bean property getter: maxLength.
      Returns:
      The property value, or null if it is not set.

    • setMaxLength

      public ParameterInfo setMaxLength(Integer value)
      Bean property setter: maxLength.
      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • getMinimum

      public Number getMinimum()
      Bean property getter: minimum.
      Returns:
      The property value, or null if it is not set.

    • setMinimum

      public ParameterInfo setMinimum(Number value)
      Bean property setter: minimum.
      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • getMinItems

      public Integer getMinItems()
      Bean property getter: minItems.
      Returns:
      The property value, or null if it is not set.

    • setMinItems

      public ParameterInfo setMinItems(Integer value)
      Bean property setter: minItems.
      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • getMinLength

      public Integer getMinLength()
      Bean property getter: minLength.
      Returns:
      The property value, or null if it is not set.

    • setMinLength

      public ParameterInfo setMinLength(Integer value)
      Bean property setter: minLength.
      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • getMultipleOf

      public Number getMultipleOf()
      Bean property getter: multipleOf.
      Returns:
      The property value, or null if it is not set.

    • setMultipleOf

      public ParameterInfo setMultipleOf(Number value)
      Bean property setter: multipleOf.
      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      Returns:
      This object.

    • getName

      public String getName()
      Bean property getter: name.

      The name of the parameter.

      Notes:
      • Parameter names are case sensitive.
      • If in is "path", the name field MUST correspond to the associated path segment from the path field in the Paths Object.
      • For all other cases, the name corresponds to the parameter name used based on the in property.
      Returns:
      The property value, or null if it is not set.

    • setName

      public ParameterInfo setName(String value)
      Bean property setter: name.

      The name of the parameter.

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

    • getPattern

      public String getPattern()
      Bean property getter: pattern.
      Returns:
      The property value, or null if it is not set.

    • setPattern

      public ParameterInfo setPattern(String value)
      Bean property setter: pattern.
      Parameters:
      value - The new value for this property.
      This string SHOULD be a valid regular expression.
      Can be null to unset the property.
      Returns:
      This object.

    • getRequired

      public Boolean getRequired()
      Bean property getter: required.

      Determines whether this parameter is mandatory.

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

    • setRequired

      public ParameterInfo setRequired(Boolean value)
      Bean property setter: required.

      Determines whether this parameter is mandatory.

      Parameters:
      value - The new value for this property.
      If the parameter is in "path", this property is required and its value MUST be true.
      Otherwise, the property MAY be included and its default value is false.
      Can be null to unset the property.
      Returns:
      This object.

    • getSchema

      public SchemaInfo getSchema()
      Bean property getter: schema.

      The schema defining the type used for the body parameter.

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

    • setSchema

      public ParameterInfo setSchema(SchemaInfo value)
      Bean property setter: schema.

      The schema defining the type used for the body parameter.

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

    • getType

      public String getType()
      Bean property getter: type.

      The type of the parameter.

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

    • setType

      public ParameterInfo setType(String value)
      Bean property setter: type.

      The type of the parameter.

      Parameters:
      value - The new value for this property.
      Valid values:
      • "string"
      • "number"
      • "integer"
      • "boolean"
      • "array"
      • "file"

      If type is "file", the consumes MUST be either "multipart/form-data", "application/x-www-form-urlencoded" or both and the parameter MUST be in "formData".
      Property value is required.
      Can be null to unset the property.
      Returns:
      This object.

    • getUniqueItems

      public Boolean getUniqueItems()
      Bean property getter: uniqueItems.
      Can be null to unset the property.
      Returns:
      The property value, or null if it is not set.

    • setUniqueItems

      public ParameterInfo setUniqueItems(Boolean value)
      Bean property setter: uniqueItems.
      Parameters:
      value - The new value for this property.
      Returns:
      This object.

    • getExample

      public Object getExample()
      Bean property getter: example.

      An example of the parameter. This is useful for documentation purposes.

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

    • setExample

      public ParameterInfo setExample(Object value)
      Bean property setter: example.

      An example of the parameter. This is useful for documentation purposes.

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

    • getExamples

      public Map<String,String> getExamples()
      Bean property getter: examples.

      Examples of the parameter. This is useful for documentation purposes.

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

    • setExamples

      public ParameterInfo setExamples(Map<String,String> value)
      Bean property setter: examples.

      Examples of the parameter. This is useful for documentation purposes.

      Parameters:
      value - The new value for this property.
      Can be null to unset the property.
      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 ParameterInfo 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.

    • resolveRefs

      public ParameterInfo resolveRefs(Swagger swagger, Deque<String> refStack, int maxDepth)
      Resolves any "$ref" attributes in this element.
      Parameters:
      swagger - The swagger document containing the definitions.
      refStack - Keeps track of previously-visited references so that we don't cause recursive loops.
      maxDepth - The maximum depth to resolve references.
      After that level is reached, $ref references will be left alone.
      Useful if you have very complex models and you don't want your swagger page to be overly-complex.
      Returns:
      This object with references resolved.
      May or may not be the same object.