Package org.eclipse.microprofile.openapi.annotations.tags

Annotation Type Tag


  • @Target({TYPE,METHOD})
@Retention(RUNTIME)
@Repeatable(Tags.class)
@Inherited
public @interface Tag
    This object represents a tag. A tag is meta-information you can use to help organize your API end-points and it can appear in two contexts.

    Define tag objects on a method that implements an operation or on a class that contains operations. They will be gathered and stored in the root object of the OpenAPI document.

    If the tag annotation definition is associated with a method that corresponds to an operation then the tag name will be added to the OpenAPI document and also be added to the operation tags.

    Reference to a Tag can be created by setting the 'ref' attribute.

    If the Tag annotation is specified on a class then each operation in the class will inherit the tag unless the operation specifies Tag(s). An operation can specify an empty Tag to not to be associated with any tag(s) inherited from the class.

    This annotation is Repeatable.

    If more than one tag is defined with the same name then only one tag with that name will appear in the OpenAPI document and the results are implementation dependent.

    Note: If both Tag and Tags annotations are specified on the same method or class, then both tag definitions should be applied. 

     @Tag(name = "luggage", description = "Operations related to luggage handling.")
 @GET
 public Location getLuggage(LuggageID id) {
     return getLuggageLocation(id);
 }
 
     @Tag(ref = "Bookings")
 @GET
 public Location getBookings() {
     return Response.ok().entity(bookings.values()).build();
 }
    See Also:
    OpenAPI Specification Tag Object

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      java.lang.String description
      A short description for this tag.
      ExternalDocumentation externalDocs
      Additional external documentation for this tag.
      java.lang.String name
      The name of this tag.
      java.lang.String ref
      Reference value to a Tag object.

    • Element Detail

      • name

        java.lang.String name
        The name of this tag. The name must be unique and is case sensitive. It is a REQUIRED property unless this is only a reference to a tag instance.
        Returns:
        the name of this tag
        Default:
        ""

      • description

        java.lang.String description
        A short description for this tag.
        Returns:
        the description of this tag
        Default:
        ""

      • externalDocs

        ExternalDocumentation externalDocs
        Additional external documentation for this tag.
        Returns:
        the external documentation for this tag
        Default:
        @org.eclipse.microprofile.openapi.annotations.ExternalDocumentation

      • ref

        java.lang.String ref
        Reference value to a Tag object.

        This property provides a reference to an object defined elsewhere. This property and all other properties are mutually exclusive. If other properties are defined in addition to the ref property then the result is undefined.

        Returns:
        reference to a tag
        Default:
        ""