Точное назначение тегов в OpenAPI и почему они уникальны

Question

По спецификации:

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

Список тегов, используемых в спецификации, с дополнительными метаданными.Порядок тегов может использоваться для отражения их порядка с помощью инструментов синтаксического анализа.Не все теги, которые используются объектом операции, должны быть объявлены.Теги, которые не объявлены, МОГУТ быть организованы случайным образом или основаны на логике инструментов.Каждое имя тега в списке ДОЛЖНО быть уникальным.

Как эти теги используются в синтаксических анализаторах, можете ли вы привести некоторые примеры?А также почему нужно быть уникальным?

Answer 1

Несколько примеров:

• Swagger UI использует теги для группы отображаемых операций.Например, демоверсия Petstore имеет три тега - pet, store и user.

• Swagger Codegen использует теги группирует конечные точки в один и тот же файл класса API :

  Например, конечная точка с "store" tags будет сгенерирована в файле класса StoreApi.

А также, почему они должны быть уникальными?

Имена тегов должны быть уникальными в том смысле, что вы не можете иметь два тега с одинаковым именем.

# 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