Annotation Interface ApiDocResponse

@Retention(RUNTIME) @Target({METHOD,CONSTRUCTOR,TYPE,PACKAGE}) @Repeatable(ApiDocResponses.class) @Documented public @interface ApiDocResponse
Adds an explicit response entry to generated API documentation.

Handler return types are inferred automatically. Use this annotation for additional status codes, error responses, response descriptions that cannot be derived from the method signature, or a composed independent-model graph whose runtime representation is an untyped JSON tree.

See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    int
    status
    HTTP status code.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    contentType
    Optional response content type.
    String
    description
    Response description.
    Class<?>
    modelGraph
    Optional root model of a composed independent-model graph response.
    String[]
    modelGraphPaths
    Optional relationship paths to include in the documented model graph.
    String
    ref
    Optional reusable response reference.
    Class<?>
    type
    Optional response body type.

  • Element Details

    • status

      int status
      HTTP status code.

    • description

      String description
      Response description.
      Default:
      ""

    • ref

      String ref
      Optional reusable response reference.

      A bare value such as error is resolved to #/components/responses/error. A value starting with #/ is used as-is. When set, description(), type(), modelGraph(), modelGraphPaths(), and contentType() are ignored because OpenAPI Reference Objects cannot have response-object siblings in OpenAPI 3.0.

      Default:
      ""

    • type

      Class<?> type
      Optional response body type. Void.class means no explicit type was provided.
      Default:
      java.lang.Void.class

    • modelGraph

      Class<?> modelGraph
      Optional root model of a composed independent-model graph response.

      Use this when a handler returns a JsonNode (or another untyped JSON representation) produced from a model graph. The generated schema starts with this model and follows child relationships that declare both a Parent.pathInParent and optional relationship documentation through Parent.apiDoc. This option is mutually exclusive with type(). When the handler returns an array or collection, the response remains an array whose items are graphs rooted at this model.

      Default:
      java.lang.Void.class

    • modelGraphPaths

      String[] modelGraphPaths
      Optional relationship paths to include in the documented model graph.

      Paths are relative to modelGraph() and use the slash-separated values declared by Parent.pathInParent. Ancestors of a selected path are included automatically, so selecting locations/connections/meters includes the locations and connections relationships as well. An empty array preserves the default of including every documented relationship below the root model.

      Default:
      {}

    • contentType

      String contentType
      Optional response content type.
      Default:
      ""