Шаг 1: объект openapi |
> | Шаг 2: объект info |
> | Шаг 3: объект servers |
> | Шаг 4: объект paths |
> | Шаг 5: объект components |
> | Шаг 6: объект security |
> | Шаг 7: объект tags |
> | Шаг 8: объект externalDocs |
Объект tags позволяет группировать пути (конечные точки) в 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 путями описания. Вы наверняка захотите организовать пути в логические группы для навигации пользователей.