Swagger для вашего API

При разработке веб-приложений часто возникает необходимость в 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.

openapi: 3.0.0
info:
  title: API для сервиса записей к врачу
  description: API для работы с записями пациентов
  version: 1.0.0
paths:
  /appointments:
    get:
      summary: Получить список записей
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    doctor:
                      type: string
                    time:
                      type: string

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

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

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

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

npm install swagger-ui-express

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

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const yaml = require('yamljs');
const swaggerDocument = yaml.load('./swagger.yaml');

const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.listen(3000, () => {
  console.log('Сервер запущен на http://localhost:3000/api-docs');
});

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

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

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

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

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

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

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

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

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

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

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

import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { INestApplication } from '@nestjs/common';

export function setupSwagger(app: INestApplication) {
  const config = new DocumentBuilder()
    .setTitle('Документация API')
    .setDescription('Описание API для проекта')
    .setVersion('1.0')
    .addTag('users')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api-docs', app, document);
}

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

Заключение

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