Annotation Interface OpenApi.Parameter

Enclosing class:
OpenApi
@Target({METHOD,PARAMETER}) @Retention(CLASS) @Repeatable(OpenApi.Parameters.class) @Documented public static @interface OpenApi.Parameter
OpenAPI Parameter Object metadata.

On a method parameter, this annotation decorates the generated parameter from the declarative HTTP binding; it cannot change the bound parameter name() or in() location. On a method, this annotation must declare non-blank name() and in() values which match an existing generated path, query, header, or cookie parameter.

Path parameters are always required and cannot be made optional. Query, header, and cookie parameters which are required by the Java signature or HTTP binding cannot be made optional. allowReserved() can be used only for query parameters. If content() is configured, style() and explode() must not be configured.

Generated OpenAPI omits declarative header parameters named Accept, Content-Type, or Authorization. Use media type metadata, request body metadata, or security metadata to describe those concerns.

  • Element Details

    • value

      String value
      Parameter description.
      Returns:
      description
      Default:
      ""

    • name

      String name
      Parameter name. Defaults to the HTTP binding name on parameter-target usage.

      Method-target usage requires a non-blank value matching a generated parameter. Parameter-target usage cannot override the generated parameter name.

      Returns:
      name
      Default:
      ""

    • in

      String in
      Parameter location. Defaults to the HTTP binding location on parameter-target usage.

      Method-target usage requires a non-blank value matching a generated parameter location. Supported generated locations are path, query, header, and cookie. Parameter-target usage cannot override the generated parameter location.

      Declarative OpenAPI annotations do not support OpenAPI 3.2 querystring parameters. To use one, define the complete containing operation in a static OpenAPI document or an OpenApiDocumentSource, and configure Helidon not to generate the same path and method from annotations.

      Returns:
      location
      Default:
      ""

    • required

      OpenApi.Required required
      Requiredness override.

      Path parameters are always required. Required query, header, and cookie parameters cannot be made optional.

      Returns:
      requiredness
      Default:
      UNSPECIFIED

    • example

      String example
      Parameter example.

      Mutually exclusive with examples(). Can be used with generated schema parameters or explicit content().

      Returns:
      example
      Default:
      ""

    • examples

      OpenApi.Example[] examples
      Parameter examples.

      Mutually exclusive with example(). Can be used with generated schema parameters or explicit content().

      Returns:
      examples
      Default:
      {}

    • content

      OpenApi.Content[] content
      Parameter content entries.

      At most one entry is supported. When configured, generated schema, style(), and explode() are omitted. Parameter example() or examples() can still be configured.

      Returns:
      content
      Default:
      {}

    • style

      OpenApi.Style style
      Parameter style.

      Must remain unspecified when content() is configured. See OpenApi.Style for supported styles by parameter location.

      Returns:
      style
      Default:
      UNSPECIFIED

    • explode

      OpenApi.Explode explode
      Parameter explode override.

      Must remain unspecified when content() is configured. Header parameters cannot use OpenApi.Explode.TRUE. Query parameters cannot use OpenApi.Explode.TRUE with OpenApi.Style.SPACE_DELIMITED or OpenApi.Style.PIPE_DELIMITED.

      Returns:
      explode
      Default:
      UNSPECIFIED

    • allowReserved

      boolean allowReserved
      Whether reserved characters are allowed unencoded.

      Supported only for query parameters.

      Returns:
      allow reserved flag
      Default:
      false

    • deprecated

      boolean deprecated
      Whether the parameter is deprecated.
      Returns:
      deprecated flag
      Default:
      false