Annotation Interface ApiDocInfo

@Retention(RUNTIME) @Target({PACKAGE,TYPE}) @Documented public @interface ApiDocInfo
Adds top-level metadata to generated API documentation.

Place this annotation on a package or handler type to describe the generated API document itself. Compiler options such as -Afluxzero.openapi.title=... can still override the same values for annotation-processor output.

  • Element Details

    • openApiVersion

      String openApiVersion
      OpenAPI document version. Defaults to 3.0.1; set 3.1.0 when a consumer requires OpenAPI 3.1.
      Default:
      ""

    • title

      String title
      API title.
      Default:
      ""

    • version

      String version
      API version.
      Default:
      ""

    • description

      String description
      API description. Markdown is allowed by OpenAPI tooling.
      Default:
      ""

    • termsOfService

      String termsOfService
      Terms of service URL.
      Default:
      ""

    • contactName

      String contactName
      Contact name.
      Default:
      ""

    • contactUrl

      String contactUrl
      Contact URL.
      Default:
      ""

    • contactEmail

      String contactEmail
      Contact email address.
      Default:
      ""

    • licenseName

      String licenseName
      License name.
      Default:
      ""

    • licenseUrl

      String licenseUrl
      License URL.
      Default:
      ""

    • logoUrl

      String logoUrl
      Optional logo URL, rendered as the common info.x-logo.url vendor extension.
      Default:
      ""

    • logoAltText

      String logoAltText
      Optional logo alt text, rendered as info.x-logo.altText.
      Default:
      ""

    • servers

      ApiDocServer[] servers
      API servers.
      Default:
      {}

    • security

      String[] security
      Top-level OpenAPI security requirements.

      Values are rendered as security requirement objects. Use bearerAuth for a scheme without scopes, or oauth2=read,write for scoped schemes. Define the actual schemes through components() with paths such as securitySchemes.bearerAuth.

      Default:
      {}

    • serveOpenApi

      boolean serveOpenApi
      If true, the generated OpenAPI document is served as an automatic web endpoint.

      The endpoint is only registered for handlers in the annotated package or type. Use openApiPath() to avoid route conflicts with application endpoints.

      Default:
      false

    • openApiPath

      String openApiPath
      Path where the generated OpenAPI document is served when serveOpenApi() is enabled.

      This endpoint is also served when serveApiReference() is enabled, because the generated HTML reference page needs an OpenAPI document to render.

      Relative paths are resolved against the Path value at the same package or handler type where this annotation is placed. Absolute paths start at the application root.

      Default:
      "openapi.json"

    • serveApiReference

      boolean serveApiReference
      If true, a small HTML API reference endpoint is served for the generated OpenAPI document.

      The endpoint uses apiReferenceRenderer() and references externally hosted or self-hosted renderer assets. The SDK does not bundle Redoc, Scalar, Swagger UI, or other frontend assets.

      Default:
      false

    • apiReferencePath

      String apiReferencePath
      Path where the generated API reference HTML page is served when serveApiReference() is enabled.

      Relative paths are resolved against the Path value at the same package or handler type where this annotation is placed. Absolute paths start at the application root.

      Default:
      "docs"

    • apiReferenceRenderer

      ApiReferenceRenderer apiReferenceRenderer
      Renderer used for the generated API reference HTML page.
      Default:
      REDOC

    • apiReferenceScriptUrl

      String apiReferenceScriptUrl
      Optional renderer script URL. Leave empty to use the SDK default for apiReferenceRenderer().

      Set this to a self-hosted URL when CDN access is not desired.

      Default:
      ""

    • apiReferenceStylesheetUrl

      String apiReferenceStylesheetUrl
      Optional renderer stylesheet URL. Leave empty to use the SDK default for apiReferenceRenderer() when it has one.

      This is mainly useful for Swagger UI.

      Default:
      ""

    • components

      ApiDocComponent[] components
      Extra OpenAPI components such as shared responses or security schemes. Component paths are relative to the OpenAPI components object, for example responses.error.
      Default:
      {}

    • extensions

      String[] extensions
      Top-level OpenAPI vendor extensions as name=json entries, for example x-code-samples-enabled=true. Values are parsed as JSON when possible and otherwise rendered as strings.
      Default:
      {}