step7-tags-object.md

Руководство OpenAPI Шаг 7: Объект tags

| Шаг 1: объект openapi | --> | Шаг 2: объект info | --> | Шаг 3: объект servers | --> | Шаг 4: объект paths | --> | Шаг 5: объект components | --> | Шаг 6: объект security | --> | Шаг 7: объект tags | --> | Шаг 8: объект externalDocs |

Объект tags позволяет группировать пути (конечные точки) в Swagger UI.

Определение tags на корневом уровне

tags на уровне объекта paths

Отображение в Swagger UI

Определение tags на корневом уровне

На корневом уровне объект tags перечисляет все теги, которые используются в объектах operations (которые появляются в объекте paths, как описано в Шаге 4: объект paths ). Вот пример объекта тегов для нашего API OpenWeatherMap:

tags:
  - name: Current Weather Data
  description: "Get current weather details"

Здесь только один тег, но их может быть столько, сколько вы хотите (если у вас много конечных точек, имеет смысл создать несколько тегов для их группировки). Вы можете перечислить как name, так и description для каждого тега. description отображается в виде подзаголовка для имени тега на дисплее пользовательского интерфейса Swagger.

Тэги на уровне объекта paths

Объект tags на корневом уровне должен содержать список всех тегов (групп), которые вы хотите использовать в своем API. Затем в каждом объекте пути под paths вы указываете тег, под которым вы хотите сгруппировать этот путь.

Например, в объекте операций для /current пути мы использовали тег Current Weather Data:

paths:
  /weather:
    get:
      tags:
      - Current Weather Data

Этот тег определен на глобальном уровне, поэтому путь /weather будет сгруппирован здесь.

Отображение в Swagger UI

Добавьте следующий код к корневому уровню документа OpenAPI в редакторе Swagger:

tags:
  - name: Current Weather Data
  description: "Get current weather details"

Посмотрите, как описание отображается рядом со свернутым разделом «Данные о текущей погоде».

Тэг определен на корневом уровне

Все пути, имеющие одинаковый тег, сгруппированы на дисплее. Например, пути с тегом Current Weather Data будут сгруппированы под заголовком Current Weather Data. Каждое название группы представляет собой кнопку, которая сворачивает / разворачивает вложенную информацию.

Порядок тегов в объекте tags на корневом уровне определяет их порядок в интерфейсе Swagger. Кроме того, descriptions появляются справа от имени тега.

В нашем примере спецификации OpenAPI теги не кажутся необходимыми, поскольку мы просто документируем один путь / конечную точку. (Кроме того, настроена демо версию Swagger UI для расширения раздела по умолчанию.) Но представьте, что у вас есть надежный API с более чем 30 путями описания. Вы наверняка захотите организовать пути в логические группы для навигации пользователей.

🔙

Go next ➡