Annotation Interface ApiDoc

@Retention(RUNTIME) @Target({METHOD,CONSTRUCTOR,TYPE,PACKAGE,FIELD,PARAMETER,RECORD_COMPONENT,TYPE_USE}) @Documented public @interface ApiDoc
Adds optional human-readable API documentation metadata to generated API docs.

Generated endpoint documentation is opt-in. Place @ApiDoc on a package, handler type, or handler method to include the matching web endpoints; an empty annotation is enough when route, parameter, request, and response information can be inferred from the existing web handler annotations. Use populated @ApiDoc values only for metadata that cannot be inferred reliably, such as descriptions, tags, or a stable operation id. The annotation can also be used on fields, parameters, record components, and type uses; for example List<@ApiDoc(description = "Connection item") Connection> documents array items without requiring OpenAPI-specific array annotations. Schema hints such as type(), format(), example(), defaultValue(), and allowableValues() provide an SDK-native alternative for the common documentation metadata that projects often express with OpenAPI-specific annotations.

When using the annotation processor, source Javadoc on schema types and properties in the same javac compilation is used as a final description fallback after explicit @ApiDoc metadata and OpenAPI @Schema metadata. Javadoc from already compiled dependency classes is not available to javac processors; use @ApiDoc when schema documentation must cross module boundaries.

See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String[]
    allowableValues
    Optional allowed string values for enum-like schemas.
    String
    defaultValue
    Optional schema default value.
    boolean
    deprecated
    Marks generated operations as deprecated.
    String
    description
    Longer description for the domain or endpoint.
    String
    example
    Optional schema example.
    String
    format
    Optional schema format override.
    Class<?>
    implementation
    Optional schema implementation override for abstract, interface, or otherwise ambiguous fields.
    String
    maximum
    Optional inclusive numeric maximum.
    String
    minimum
    Optional inclusive numeric minimum.
    String
    operationId
    Stable operation identifier for generated specs.
    boolean
    required
    Marks a schema property or parameter as required in generated docs.
    String[]
    security
    OpenAPI security requirements for generated operations.
    String
    summary
    Short endpoint summary.
    String[]
    tags
    Tags to associate with generated operations.
    String
    type
    Optional schema type override, such as string, integer, number, boolean, object, or array.

  • Element Details

    • summary

      String summary
      Short endpoint summary.
      Default:
      ""

    • description

      String description
      Longer description for the domain or endpoint.
      Default:
      ""

    • operationId

      String operationId
      Stable operation identifier for generated specs.
      Default:
      ""

    • tags

      String[] tags
      Tags to associate with generated operations.
      Default:
      {}

    • type

      String type
      Optional schema type override, such as string, integer, number, boolean, object, or array. Values date, date-time, uuid, uri, email, and binary are treated as string formats.
      Default:
      ""

    • format

      String format
      Optional schema format override.
      Default:
      ""

    • example

      String example
      Optional schema example. JSON object/array examples are parsed when possible; scalar examples are coerced to the inferred schema type when possible.
      Default:
      ""

    • defaultValue

      String defaultValue
      Optional schema default value. Values are coerced to the inferred schema type when possible.
      Default:
      ""

    • minimum

      String minimum
      Optional inclusive numeric minimum.
      Default:
      ""

    • maximum

      String maximum
      Optional inclusive numeric maximum.
      Default:
      ""

    • allowableValues

      String[] allowableValues
      Optional allowed string values for enum-like schemas.
      Default:
      {}

    • required

      boolean required
      Marks a schema property or parameter as required in generated docs.
      Default:
      false

    • implementation

      Class<?> implementation
      Optional schema implementation override for abstract, interface, or otherwise ambiguous fields.
      Default:
      java.lang.Void.class

    • deprecated

      boolean deprecated
      Marks generated operations as deprecated.
      Default:
      false

    • security

      String[] security
      OpenAPI security requirements for generated operations.

      Values are rendered as security requirement objects. Use bearerAuth for a scheme without scopes, or oauth2=read,write for scoped schemes.

      Default:
      {}