Skip to main content

Swagger Tags

Tags allow you to group operations into general categories. In the user interface, these can be expanded/collapsed by clicking on the tag sections.

In the example below, the pet and store tag sections are collapsed and the user section is not:

Swagger Tags

Tags are also defined in the @Swagger annotation

PetStoreResource.json​

"tags": [
    {
        "name": "pet",
        "description": "Everything about your Pets",
        "externalDocs": {
            "description": "Find out more",
            "url": "http://juneau.apache.org"
        }
    },
    {
        "name": "store",
        "description": "Access to Petstore orders"
    },
    {
        "name": "user",
        "description": "Operations about user",
        "externalDocs": {
            "description": "Find out more about our store",
            "url": "http://juneau.apache.org"
        }
    }
],

The annotation-only approach is shown here:

org.apache.juneau.examples.rest.petstore.PetStoreResource​

swagger=@Swagger(
    ...
    tags={
        @Tag(
            name="pet",
            description="Everything about your Pets",
            externalDocs=@ExternalDocs(
                description="Find out more",
                url="http://juneau.apache.org"
            )
        ),
        @Tag(
            name="store",
            description="Access to Petstore orders"
        ),
        @Tag(
            name="user",
            description="Operations about user",
            externalDocs=@ExternalDocs(
                description="Find out more about our store",
                url="http://juneau.apache.org"
            )
        )
    }
),

Tags are associated with operations using the @OpSwagger(tags) annotation:

GET /user operation​

@RestGet(
    path="/user",
    summary="Petstore users",
    swagger=@OpSwagger(
        tags="user"
    )
)
public Collection getUsers() throws NotAcceptable {...}

Operations can be mapped to multiple tags.

Tags are optional.

Operations not mapped to tags are listed in the UI before tagged operations.

For example, the getTopPage() method in PetStoreResource is not tagged, as well as the getOptions() method inherited from BaseRestServlet, so these show up at the top of the page:

Swagger Untagged Operations