Пример документации Swagger

Ниже приведён полный пример документа Swagger, который представляет собой подробную спецификацию API системы управления пользователями.

Этот документ описывает API системы управления пользователями, включая основную информацию о пользователях, сервисы аутентификации, модели данных и т. д.

Этот API следует стилю RESTful и использует формат JSON для обмена данными.

Вы можете использовать Swagger Editor для онлайн-проверки вашего документа. Онлайн-адрес:https://editor.swagger.io/. Просто скопируйте и вставьте ваш YAML или JSON в редактор, и на правой панели отобразится визуализированная документация API.

Пример

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
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:
- url: https://api.example.com/v1
description:Продуктивная среда
- url: https://staging-api.example.com/v1
description:Стейджинговая среда
- url: https://dev-api.example.com/v1
description:Среда разработки

tags:
- name:User
description:Операции по управлению пользователями
- name:Authentication
description:Операции, связанные с аутентификацией

paths:
/users:
get:
tags:
-Пользователь
summary:Получить список всех пользователей
description:Возвращает всю информацию о пользователях в системе с поддержкой пагинации и фильтрации
operationId: getUsers
parameters:
- name: limit
in: query
description:Максимальное количество возвращаемых результатов
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 100
default: 20
- name: offset
in: query
description:Смещение пагинации
required: false
schema:
type: integer
format: int32
minimum: 0
default: 0
- name: status
in: query
description:Фильтр по статусу пользователя
required: false
schema:
type: string
enum: [active, inactive, banned]
responses:
'200':
description:Список пользователей успешно получен
content:
application/json:
schema:
type: object
properties:
total:
type: integer
description:Общее количество пользователей
users:
type: array
items:
$ref: '#/components/schemas/User'
пример:
total: 2
users:
- id: 1
username: "john_doe"
email: "[email protected]"
status: "active"
createdAt: "2023-05-01T12:00:00Z"
- id: 2
username: "jane_smith"
email: "[email protected]"
status: "active"
createdAt: "2023-05-02T14:30:00Z"
'400':
description:Некорректный запрос
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/UnauthorizedError'
безопасность:
- bearerAuth: []

post:
tags:
-Пользователь
summary:Создать нового пользователя
description:Создать нового пользователя в системе
operationId: createUser
requestBody:
description:Информация о пользователе
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
пример:
username: "new_user"
email: "[email protected]"
password: "securePassword123"
responses:
'201':
description:Пользователь успешно создан
content:
application/json:
schema:
$ref: '#/components/schemas/User'
пример:
id: 3
username: "new_user"
email: "[email protected]"
status: "active"
createdAt: "2023-05-10T09:15:00Z"
'400':
description:Некорректный запрос
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
пример:
code: 400
message: "Неверный формат электронной почты"
'409':
description:Конфликт ресурсов
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
пример:
code: 409
message: "Имя пользователя уже существует"
'401':
$ref: '#/components/responses/UnauthorizedError'
безопасность:
- bearerAuth: []

/users/{userId}:
parameters:
- name: userId
in: path
description:Идентификатор пользователя
required: true
schema:
type: integer
format: int64

get:
tags:
-Пользователь
summary:Получить конкретного пользователя
description:Получить подробную информацию о конкретном пользователе по ID
operationId: getUserById
responses:
'200':
description:Информация о пользователе успешно получена
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetail'
пример:
id: 1
username: "john_doe"
email: "[email protected]"
firstName: "Джон"
lastName: "Доу"
phone: "+1234567890"
status: "active"
createdAt: "2023-05-01T12:00:00Z"
lastLogin: "2023-05-10T08:30:00Z"
'404':
description:Пользователь не найден
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
пример:
code: 404
message: "Пользователь не найден"
'401':
$ref: '#/components/responses/UnauthorizedError'
безопасность:
- bearerAuth: []

put:
tags:
-Пользователь
summary:Обновить информацию о пользователе
description:Обновить информацию о конкретном пользователе
operationId: updateUser
requestBody:
description:Обновленная информация о пользователе
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUser'
пример:
firstName: "Джонатан"
lastName: "Доу"
phone: "+1987654321"
responses:
'200':
description:Информация о пользователе успешно обновлена
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetail'
'400':
description:Некорректный запрос
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description:Пользователь не найден
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/UnauthorizedError'
безопасность:
- bearerAuth: []

удаление:
tags:
-Пользователь
summary:Удалить пользователя
description:Удалить конкретного пользователя из системы
operationId: deleteUser
responses:
'204':
description:Пользователь успешно удален
'404':
description:Пользователь не найден
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/UnauthorizedError'
безопасность:
- bearerAuth: []

/auth/login:
post:
tags:
-Аутентификация
summary:Вход пользователя
description:Пользователь входит в систему и получает токен доступа
operationId: login
requestBody:
description:Учётные данные для входа
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
description:Имя пользователя
пароль:
type: string
format: password
description:Пароль
required:
- username
- пароль
пример:
username: "john_doe"
password: "password123"
responses:
'200':
description:Вход выполнен успешно
content:
application/json:
schema:
type: object
properties:
accessToken:
type: string
description:JWT-токен доступа
tokenType:
type: string
description:Тип токена
expiresIn:
type: integer
description:Время истечения срока действия токена (seconds)
пример:
accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
tokenType: "Bearer"
expiresIn: 3600
'401':
description:Ошибка входа
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
пример:
code: 401
message: "Неверное имя пользователя или пароль"

/auth/register:
post:
tags:
-Аутентификация
summary:Регистрация пользователя
description:Зарегистрировать нового пользователя и получить токен доступа
operationId: register
requestBody:
description:Информация для регистрации
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'201':
description:Регистрация прошла успешно
content:
application/json:
schema:
type: object
properties:
user:
$ref: '#/components/schemas/User'
accessToken:
type: string
description:JWT-токен доступа
пример:
user:
id: 3
username: "new_user"
email: "[email protected]"
status: "active"
createdAt: "2023-05-10T09:15:00Z"
accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
'400':
description:Некорректный запрос
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
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

UserDetail:
allOf:
- $ref: '#/components/schemas/User'
- type: object
properties:
firstName:
type: string
description:Имя
lastName:
type: string
description:Фамилия
phone:
type: string
description:Номер телефона
lastLogin:
type: string
format: date-time
description:Время последнего входа

NewUser:
type: object
properties:
username:
type: string
description:Имя пользователя
minLength: 3
maxLength: 50
email:
type: string
format: email
description:Электронная почта пользователя
пароль:
type: string
format: password
description:Пароль пользователя
minLength: 8
maxLength: 100
firstName:
type: string
description:Имя
lastName:
type: string
description:Фамилия
phone:
type: string
description:Номер телефона
required:
- username
- email
- пароль

UpdateUser:
type: object
properties:
email:
type: string
format: email
description:Электронная почта пользователя
firstName:
type: string
description:Имя
lastName:
type: string
description:Фамилия
phone:
type: string
description:Номер телефона
пароль:
type: string
format: password
description:Новый пароль (при изменении)
minLength: 8
maxLength: 100

Ошибка:
type: object
properties:
code:
type: integer
format: int32
description:Код ошибки
message:
type: string
description:Сообщение об ошибке
required:
- code
- message

responses:
UnauthorizedError:
description:Токен доступа отсутствует или недействителен
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
пример:
code: 401
message: "Неавторизованный доступ"

securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description:Аутентификация с использованием JWT Bearer Token

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

Далее перечислены основные компоненты документа:

1. Раздел основной информации

Название и описание API: Основные функции системы управления пользователями
Информация о версии：1.0.0
Контактная информация: Контактная информация команды поддержки API
Лицензия：Apache 2.0

2. Конфигурация сервера

Производственная среда
Среда промежуточного развертывания
Среда разработки

3. Классификация тегов API

Операции, связанные с пользователями
Операции, связанные с аутентификацией

4. Пути и операции

Этот API включает следующие конечные точки:

Управление пользователями

GET /users- Получить список всех пользователей (поддерживает пагинацию и фильтрацию)
POST /users- Создать нового пользователя
GET /users/{userId}- Получить сведения о конкретном пользователе
PUT /users/{userId}- Обновить информацию о пользователе
DELETE /users/{userId}- Удалить пользователя

Служба аутентификации

POST /auth/login- Вход пользователя
POST /auth/register- Регистрация пользователя

5. Модели данных

User- Базовая информация о пользователе
UserDetail- Подробная информация о пользователе
NewUser- Тело запроса для создания пользователя
UpdateUser- Тело запроса для обновления пользователя
Error- Ответ об ошибке

6. Определения безопасности

Используйте JWT Bearer Token для аутентификации API.

Этот документ соответствует спецификации OpenAPI 3.0.0 и включает полные параметры запросов, коды состояния ответов, определения моделей данных и примеры значений. Вы можете скопировать этот YAML-документ в Swagger Editor, чтобы увидеть визуализацию, или интегрировать его в свой проект.

Этот документ может служить основой для разработки вашего RESTful API и может быть дополнительно расширен и улучшен по мере роста проекта.

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