Package com.kosdev.kos.commons.core.dispatcher.annotations

Annotation Interface ApiController

@Target(TYPE) @Retention(RUNTIME) @Documented public @interface ApiController
Class annotation that indicates that the class contains endpoints. An endpoint is indicated by the ApiEndpoint annotation on a method. The title and desc parameters should be populated as this data is consumed by the openApi integration within KOS to make the endpoints discoverable.

A base url can optionally be specified in the @ApiController annotation. This will be prefixed to every endpoint defined within the controller. For example, to prefix all mappings with "/myService", use @ApiController(base = "/myService").

Endpoints support versioning via the @{code version} parameter. This will define the default version of all @ApiEndpoint's in the controller class unless they override the version independently. The version will be returned as part of the standard KOS response envelope.

Since:
1
Version:
9

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    base
    Base path for mappings.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    accessGrant
    If set, all endpoints in this controller are only accessible when the specified grant expression is true.
    String
    desc
    Description of the controller for OpenApi docs.
    boolean
    hidden
    If true, don't include in OpenApi docs.
    String
    title
    Title of the controller for OpenApi docs.
    String
    version
    The default api version.
    String
    visibleGrant
    If set, the controller and all endpoints will not be visible unless the grant expression is true.

  • Element Details

    • base

      String base
      Base path for mappings.
      Since:
      1

    • title

      String title
      Title of the controller for OpenApi docs.
      Since:
      1
      Default:
      ""

    • desc

      String desc
      Description of the controller for OpenApi docs.
      Since:
      1
      Default:
      ""

    • version

      String version
      The default api version.
      Since:
      1
      Default:
      ""

    • hidden

      boolean hidden
      If true, don't include in OpenApi docs.
      Since:
      9
      Default:
      false

    • visibleGrant

      String visibleGrant
      If set, the controller and all endpoints will not be visible unless the grant expression is true. When grants are not available, the controller and endpoints will not appear in openApi docs and endpoints will return a 404. If an endpoint also specifies visibility, both the controller and endpoint expressions must be true to be visible.
      Since:
      9
      Default:
      ""

    • accessGrant

      String accessGrant
      If set, all endpoints in this controller are only accessible when the specified grant expression is true. If an endpoint also specifies access, the endpoint access overrides the controller access. If not visible, access is ignored. Visible endpoints without access will throw an exception.
      Since:
      9
      Default:
      ""