Написание вашего первого документа Swagger

Swagger (OpenAPI) — это спецификация и набор инструментов для описания, генерации и визуализации RESTful веб-сервисов.

Ниже я подробно расскажу, как написать ваш первый документ Swagger с нуля.

Документы Swagger в основном используют формат YAML или JSON и определяют различные аспекты API, включая:

Базовая информация об API (название, версия и т. д.)
Доступные пути и операции
Входные параметры и выходные ответы
Методы аутентификации
Определения моделей данных

Шаги создания

1. Создайте базовую структуру файла

Сначала создайте файл с именемswagger.yamlилиswagger.jsonфайл. В этом руководстве формат YAML используется в качестве примера, потому что его легче читать и записывать.

Пример
openapi: 3.0.0
информация:
title:Мой первый API
description:Это простой пример документа API
version: 1.0.0
contact:
name:Команда поддержки API
email: support@example.com
url: https://www.example.com/support
servers:
- url: https://api.example.com/v1
description:Производственная среда
- url: https://dev-api.example.com/v1
description:Среда разработки

2. Добавьте базовую информацию о документе

Пример
openapi: 3.0.0
информация:
title:Мой первый API
description:Это простой пример документа API
version: 1.0.0
contact:
name:Команда поддержки API
email: support@example.com
url: https://www.example.com/support
servers:
- url: https://api.example.com/v1
description:Производственная среда
- url: https://dev-api.example.com/v1
description:Среда разработки

3. Определите пути и операции

Пути определяют конечные точки, к которым API может получить доступ, а операции определяют HTTP-методы (GET, POST, PUT, DELETE и т. д.), которые можно выполнять над этими конечными точками.

Пример
paths:
/users:
get:
summary:Получить список всех пользователей
description:Возвращает всю информацию о пользователях в системе
operationId: getUsers
parameters:
- name: limit
in: query
description:Максимальное количество возвращаемых результатов
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 100
default: 20
responses:
'200':
description:Успешное получение списка пользователей
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
'400':
description:Некорректный запрос
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
summary:Создать нового пользователя
description:Создать нового пользователя в системе
operationId: createUser
requestBody:
description:Информация о пользователе
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'201':
description:Пользователь успешно создан
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description:Некорректный запрос
content:
application/json:
schema:
$ref: '#/components/schemas/Error'

4. Определите компоненты и модели

ВcomponentsВ этом разделе определяются переиспользуемые модели:

Пример
components:
schemas:
Пользователь:
type: object
properties:
id:
type: integer
format: int64
description:Уникальный идентификатор пользователя
username:
type: string
description:Имя пользователя
email:
type: string
format: email
description:Электронная почта пользователя
status:
type: string
enum: [active, inactive, banned]
description:Статус пользователя
createdAt:
type: string
format: date-time
description:Время создания
required:
- id
- username
- email
- status

NewUser:
type: object
properties:
username:
type: string
description:Имя пользователя
email:
type: string
format: email
description:Электронная почта пользователя
пароль:
type: string
format: password
description:Пароль пользователя
minLength: 8
required:
- username
- email
- пароль

Ошибка:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
required:
- code
- message

5. Добавьте определения безопасности

Определите требования безопасности API:

Пример
безопасность:
- bearerAuth: []

components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT

6. Пример полного документа

Объедините все разделы выше, и вы получите полный документ Swagger.

Пример

openapi: 3.0.0
информация:
title:Мой первый API
description:Это простой пример документа API
version: 1.0.0
contact:
name:Команда поддержки API
email: support@example.com
url: https://www.example.com/support
servers:
- url: https://api.example.com/v1
description:Производственная среда
- url: https://dev-api.example.com/v1
description:Среда разработки

paths:
/users:
get:
summary:Получить список всех пользователей
description:Возвращает всю информацию о пользователях в системе
operationId: getUsers
parameters:
- name: limit
in: query
description:Максимальное количество возвращаемых результатов
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 100
default: 20
responses:
'200':
description:Успешное получение списка пользователей
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
'400':
description:Некорректный запрос
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
summary:Создать нового пользователя
description:Создать нового пользователя в системе
operationId: createUser
requestBody:
description:Информация о пользователе
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'201':
description:Пользователь успешно создан
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description:Некорректный запрос
content:
application/json:
schema:
$ref: '#/components/schemas/Error'

components:
schemas:
Пользователь:
type: object
properties:
id:
type: integer
format: int64
description:Уникальный идентификатор пользователя
username:
type: string
description:Имя пользователя
email:
type: string
format: email
description:Электронная почта пользователя
status:
type: string
enum: [active, inactive, banned]
description:Статус пользователя
createdAt:
type: string
format: date-time
description:Время создания
required:
- id
- username
- email
- status

NewUser:
type: object
properties:
username:
type: string
description:Имя пользователя
email:
type: string
format: email
description:Электронная почта пользователя
пароль:
type: string
format: password
description:Пароль пользователя
minLength: 8
required:
- username
- email
- пароль

Ошибка:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
required:
- code
- message

securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT

безопасность:
- bearerAuth: []

7. Используйте инструменты Swagger

Существует несколько способов визуализировать и протестировать ваш документ Swagger:

Swagger UI: интерактивная страница документации
Swagger Editor: онлайн-редактор, который может в реальном времени предварительно просматривать документ
Swagger Codegen: инструмент для генерации клиентского кода

8. Протестируйте документ онлайн

Вы можете использоватьSwagger Editorдля тестирования вашего документа онлайн. Просто скопируйте и вставьте ваш YAML или JSON в редактор, и на правой панели отобразится визуальный документ API.

9. Лучшие практики

Используйте осмысленные идентификаторы операций
Предоставьте подробные описания для каждого эндпоинта
Убедитесь, что все параметры имеют описания
Документируйте все возможные коды состояния ответа
Используйте ссылки на модели, чтобы уменьшить дублирование
Поддерживайте документ в актуальном состоянии
Добавьте примеры запросов и ответов для каждой конечной точки

10. Общие места расположения параметров

Swagger определяет несколько мест размещения параметров:

path: параметры в пути URL, например/users/{id}
query: параметры запроса URL, например/users?limit=10
header: параметры заголовков HTTP
cookie: параметры Cookie
body: параметры тела запроса (в OpenAPI 3.0 вместо этого используется requestBody)

11. Расширьте ваш документ

По мере развития вашего API продолжайте расширять ваш документ Swagger:

Добавьте больше конечных точек
Определите дополнительные модели
Добавьте более подробные описания
Добавьте примеры запросов и ответов

12. Интеграция в реальную разработку

В реальной разработке вы можете:

Интегрировать Swagger в ваш код
Использовать инструменты автогенерации
Генерировать документацию из комментариев в коде
Встроить Swagger UI в ваше приложение

Другие расширения