Логотип

Swagger для вашего API

Енот на гамаке
508

При разработке веб-приложений часто возникает необходимость в API — интерфейсе, который позволяет программам взаимодействовать друг с другом. Однако, чтобы работать с API, нужно понимать его структуру: какие запросы можно отправлять, какие параметры передавать и что будет в ответе. Для упрощения этой задачи разработчики используют инструмент Swagger. Давайте разберемся, что это такое и как его применять на практике.

Что такое Swagger?

Swagger состоит из нескольких компонентов:

  • Swagger Editor — онлайн-редактор для написания документации в формате OpenAPI (YAML или JSON).
  • Swagger UI — визуальный интерфейс для просмотра и тестирования API в браузере.
  • Swagger Codegen — генератор клиентского кода и серверных заглушек на различных языках программирования.
  • Swagger Inspector — инструмент для автоматической генерации спецификаций API на основе реальных запросов.

Благодаря этим инструментам разработчики могут быстрее разрабатывать API, обеспечивая стандартизированное и удобное взаимодействие с ним.

Подробнее техническую документацию можно изучить на официальном сайте Swagger

Для чего используется Swagger?

Swagger решает сразу несколько важных задач:

  1. Автоматическая генерация документации. Вам не нужно вручную описывать все эндпоинты и параметры — Swagger делает это автоматически.
  2. Тестирование API. Можно сразу проверить, как API работает, отправляя запросы через Swagger UI.
  3. Облегчение интеграции. Swagger Codegen позволяет автоматически генерировать код для работы с API на разных языках.
  4. Упрощение командной работы. Разработчики, тестировщики и аналитики могут быстро разобраться в API и взаимодействовать эффективнее.
  5. Облегчение работы с внешними сервисами. Сторонние компании могут легко интегрировать ваш API, используя удобную и понятную документацию.
  6. Обучение новых разработчиков. Новый член команды может быстрее вникнуть в структуру API, используя интерактивную документацию.

Как использовать Swagger на практике?

1. Создание документации с помощью Swagger Editor

Самый простой способ создать документацию — использовать Swagger Editor. Он позволяет писать спецификацию API в формате YAML.

1openapi: 3.0.0
2info:
3  title: API для сервиса записей к врачу
4  description: API для работы с записями пациентов
5  version: 1.0.0
6paths:
7  /appointments:
8    get:
9      summary: Получить список записей
10      responses:
11        "200":
12          description: Успешный ответ
13          content:
14            application/json:
15              schema:
16                type: array
17                items:
18                  type: object
19                  properties:
20                    id:
21                      type: integer
22                    doctor:
23                      type: string
24                    time:
25                      type: string

Этот код описывает эндпоинт /appointments, который возвращает список записей к врачам.

2. Подключение Swagger UI к проекту

Swagger UI позволяет интерактивно просматривать документацию API и тестировать запросы.

Чтобы развернуть Swagger UI локально, можно использовать пакет npm:

1npm install swagger-ui-express

Пример подключения Swagger UI к Express.js:

1const express = require('express');
2const swaggerUi = require('swagger-ui-express');
3const yaml = require('yamljs');
4const swaggerDocument = yaml.load('./swagger.yaml');
5
6const app = express();
7app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
8
9app.listen(3000, () => {
10  console.log('Сервер запущен на http://localhost:3000/api-docs');
11});

Теперь документация будет доступна по адресу http://localhost:3000/api-docs.

3. Автоматическая генерация клиентского кода с Swagger Codegen

Если нужно сгенерировать клиентскую библиотеку для API, можно использовать Swagger Codegen. Устанавливаем его:

1npm install @openapitools/openapi-generator-cli -g

Генерируем код для JavaScript:

1openapi-generator-cli generate -i swagger.yaml -g javascript -o ./api-client

После этого в папке api-client появится готовая библиотека для работы с API.

4. Использование Swagger с NestJS

Если ваш проект написан на NestJS, подключить Swagger можно с помощью пакета @nestjs/swagger:

1npm install --save @nestjs/swagger swagger-ui-express

Пример настройки Swagger в NestJS:

1import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
2import { INestApplication } from '@nestjs/common';
3
4export function setupSwagger(app: INestApplication) {
5  const config = new DocumentBuilder()
6    .setTitle('Документация API')
7    .setDescription('Описание API для проекта')
8    .setVersion('1.0')
9    .addTag('users')
10    .build();
11
12  const document = SwaggerModule.createDocument(app, config);
13  SwaggerModule.setup('api-docs', app, document);
14}

Теперь Swagger UI будет доступен по адресу http://localhost:3000/api-docs.

Заключение

Swagger значительно облегчает разработку API: позволяет автоматизировать документацию, тестировать запросы и генерировать клиентский код. Он упрощает интеграцию API для внешних разработчиков и командной работы внутри компании. Использование Swagger помогает командам работать быстрее, эффективнее и с меньшим количеством ошибок. Если вы разрабатываете API, попробуйте его в действии!