Package io.swagger.annotations

Annotation Type Api

  • @Target(TYPE)
@Retention(RUNTIME)
@Inherited
public @interface Api
    Marks a class as a Swagger resource.

    By default, Swagger-Core will only include and introspect only classes that are annotated with @Api and will ignore other resources (JAX-RS endpoints, Servlets and so on).

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      Authorization[] authorizations
      Corresponds to the `security` field of the Operation Object.
      String basePath
      Deprecated.
      String consumes
      Corresponds to the `consumes` field of the operations under this resource.
      String description
      Deprecated.
      boolean hidden
      Hides the operations under this resource.
      int position
      Deprecated.
      String produces
      Corresponds to the `produces` field of the operations under this resource.
      String protocols
      Sets specific protocols (schemes) for the operations under this resource.
      String[] tags
      A list of tags for API documentation control.
      String value
      Implicitly sets a tag for the operations, legacy support (read description).

    • Element Detail

      • value

        String value
        Implicitly sets a tag for the operations, legacy support (read description).

        In swagger-core 1.3.X, this was used as the 'path' that is to host the API Declaration of the resource. This is no longer relevant in swagger-core 1.5.X.

        If tags() is not used, this value will be used to set the tag for the operations described by this resource. Otherwise, the value will be ignored.

        The leading / (if exists) will be removed.

        Returns:
        tag name for operations under this resource, unless tags() is defined.
        Default:
        ""

      • tags

        String[] tags
        A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.

        A non-empty value will override the value provided in value().

        Returns:
        a string array of tag values
        Since:
        1.5.2-M1
        Default:
        {""}

      • description

        @Deprecated
String description
        Deprecated.
        Not used in 1.5.X, kept for legacy support.
        Returns:
        a longer description about this API, no longer used.
        Default:
        ""

      • basePath

        @Deprecated
String basePath
        Deprecated.
        Not used in 1.5.X, kept for legacy support.
        Returns:
        the basePath for this operation, no longer used.
        Default:
        ""

      • position

        @Deprecated
int position
        Deprecated.
        Not used in 1.5.X, kept for legacy support.
        Returns:
        the position of this API in the resource listing, no longer used.
        Default:
        0

      • produces

        String produces
        Corresponds to the `produces` field of the operations under this resource.

        Takes in comma-separated values of content types. For example, "application/json, application/xml" would suggest the operations generate JSON and XML output.

        For JAX-RS resources, this would automatically take the value of the @Produces annotation if such exists. It can also be used to override the @Produces values for the Swagger documentation.

        Returns:
        the supported media types supported by the server, or an empty string if not set.
        Default:
        ""

      • consumes

        String consumes
        Corresponds to the `consumes` field of the operations under this resource.

        Takes in comma-separated values of content types. For example, "application/json, application/xml" would suggest the operations accept JSON and XML input.

        For JAX-RS resources, this would automatically take the value of the @Consumes annotation if such exists. It can also be used to override the @Consumes values for the Swagger documentation.

        Returns:
        the consumes value, or empty string if not set
        Default:
        ""

      • protocols

        String protocols
        Sets specific protocols (schemes) for the operations under this resource.

        Comma-separated values of the available protocols. Possible values: http, https, ws, wss.

        Returns:
        the protocols supported by the operations under the resource.
        Default:
        ""

      • authorizations

        Authorization[] authorizations
        Corresponds to the `security` field of the Operation Object.

        Takes in a list of the authorizations (security requirements) for the operations under this resource. This may be overridden by specific operations.

        Returns:
        an array of authorizations required by the server, or a single, empty authorization value if not set.
        See Also:
        Authorization
        Default:
        {@io.swagger.annotations.Authorization("")}

      • hidden

        boolean hidden
        Hides the operations under this resource.
        Returns:
        true if the api should be hidden from the swagger documentation
        Default:
        false