Package org.eclipse.microprofile.openapi.annotations.parameters

Annotation Interface Parameter

@Target({PARAMETER,METHOD,FIELD}) @Retention(RUNTIME) @Repeatable(Parameters.class) @Inherited public @interface Parameter
Describes a single operation parameter
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    allowEmptyValue
    When true, allows sending an empty value.
    boolean
    allowReserved
    Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986.
    Content[]
    content
    The representation of this parameter, for different media types.
    boolean
    deprecated
    Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.
    String
    description
    A brief description of the parameter.
    String
    example
    Provides an example of the schema.
    ExampleObject[]
    examples
    Provides an array examples of the schema.
    Explode
    explode
    When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.
    Extension[]
    extensions
    List of extensions to be added to the Parameter model corresponding to the containing annotation.
    boolean
    hidden
    Allows this parameter to be marked as hidden
    ParameterIn
    in
    The location of the parameter.
    String
    name
    The name of the parameter.
    String
    ref
    Reference value to a Parameter object.
    boolean
    required
    Determines whether this parameter is mandatory.
    Schema
    schema
    The schema defining the type used for the parameter.
    ParameterStyle
    style
    Describes how the parameter value will be serialized depending on the type of the parameter value.

  • Element Details

    • name

      String name
      The name of the parameter. Parameter names are case sensitive. It is a REQUIRED property unless this is only a reference to a parameter instance.

      When the parameter is defined within Components, the name will be used as the key to add this parameter to the 'parameters' map for reuse.

      If in is "path", the name field MUST correspond to the associated path segment from the path field in the Paths Object. See Path Templating for further information.

      If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored.

      For all other cases, the name corresponds to the parameter name used by the in property.

      Returns:
      this parameter's name
      Default:
      ""

    • in

      ParameterIn in
      The location of the parameter. It is a REQUIRED property unless this is only a reference to a parameter instance.

      Possible values are specified in ParameterIn enum. Ignored when empty string.

      Returns:
      this parameter's location
      Default:
      DEFAULT

    • description

      String description
      A brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
      Returns:
      this parameter's description
      Default:
      ""

    • required

      boolean required
      Determines whether this parameter is mandatory.

      If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property may be included and its default value is false.

      Returns:
      whether or not this parameter is required
      Default:
      false

    • deprecated

      boolean deprecated
      Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.
      Returns:
      whether or not this parameter is deprecated
      Default:
      false

    • allowEmptyValue

      boolean allowEmptyValue
      When true, allows sending an empty value. If false, the parameter will be considered \"null\" if no value is present.

      This may create validation errors when the parameter is required. Valid only for query parameters and allows sending a parameter with an empty value.

      If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored.
      Returns:
      whether or not this parameter allows empty values
      Default:
      false

    • style

      ParameterStyle style
      Describes how the parameter value will be serialized depending on the type of the parameter value.

      Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

      Ignored if the properties content or array are specified.
      Returns:
      the style of this parameter
      Default:
      DEFAULT

    • explode

      Explode explode
      When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

      For other types of parameters this property has no effect. When style is form, the default value is true. For all other styles, the default value is false.

      Ignored if the properties content or array are specified.
      Returns:
      whether or not to expand individual array members
      Default:
      DEFAULT

    • allowReserved

      boolean allowReserved
      Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986.

      This property only applies to parameters with an in value of query. Ignored if the properties content or array are specified.

      Returns:
      whether or not this parameter allows reserved characters
      Default:
      false

    • schema

      Schema schema
      The schema defining the type used for the parameter. Ignored if the properties content or array are specified.
      Returns:
      the schema of this parameter
      Default:
      @org.eclipse.microprofile.openapi.annotations.media.Schema

    • content

      Content[] content
      The representation of this parameter, for different media types.
      Returns:
      the content of this parameter
      Default:
      {}

    • hidden

      boolean hidden
      Allows this parameter to be marked as hidden
      Returns:
      whether or not this parameter is hidden
      Default:
      false

    • examples

      ExampleObject[] examples
      Provides an array examples of the schema. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. Furthermore, if referencing a schema which contains an example, the examples value SHALL override the example provided by the schema.

      When associated with a specific media type, the example string shall be parsed by the consumer to be treated as an object or an array.

      Ignored if the properties content or array are specified.
      Returns:
      the list of examples for this parameter
      Default:
      {}

    • example

      String example
      Provides an example of the schema. The example SHOULD match the specified schema and encoding properties if present. Furthermore, if referencing a schema which contains an example, the example value SHALL override the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

      When associated with a specific media type, the example string SHALL be parsed by the consumer to be treated as an object or an array.

      Ignored if the properties examples, content or array are specified.
      Returns:
      an example of the parameter
      Default:
      ""

    • ref

      String ref
      Reference value to a Parameter object.

      This property provides a reference to an object defined elsewhere. This property and all other properties are mutually exclusive. If other properties are defined in addition to the ref property then the result is undefined.

      Returns:
      reference to a parameter
      Default:
      ""

    • extensions

      Extension[] extensions
      List of extensions to be added to the Parameter model corresponding to the containing annotation.
      Returns:
      array of extensions
      Since:
      3.1
      Default:
      {}