Exact purpose of tags in OpenAPI and why are they unique

Question

By Specification:

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the Operation Object must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.

How are these tags used in parsers, can you provide some examples? And also why need to be unique?.

Answer 1

A couple of examples:

• Swagger UI uses tags to group the displayed operations. For example, the Petstore demo has three tags - pet, store and user.

• Swagger Codegen uses tags to group endpoints into the same API class file:

  For example, an endpoint with the "store" tags will be generated in the StoreApi class file.

And also why need to be unique?

Tag names must be unique in the sense that you cannot have two tags with the same name.

# Correct
openapi: 3.0.2
tags:
  - name: pet    # <--- unique tag name
    description: Operations to manage the pets

  - name: store  # <--- unique tag name
    descriptions: Access to Petstore orders


# Wrong
openapi: 3.0.2
tags:
  - name: pet
  - name: pet