Основные компоненты Swagger

Swagger — это набор инструментов с открытым исходным кодом, построенный вокруг спецификации OpenAPI и используемый для проектирования, создания, документирования и использования RESTful API.

Swagger предоставляет стандартизированный способ описания структуры API, позволяя как разработчикам, так и машинам понимать функциональность API без доступа к исходному коду или другой документации.

Основные ценности Swagger:

  • Стандартизация: Обеспечивает единый формат описания API
  • Визуализация: Автоматически генерирует интерактивную документацию API
  • Тестируемость: Позволяет тестировать конечные точки API прямо в документации
  • Генерация кода: Поддерживает генерацию клиентского и серверного кода на нескольких языках

Основные компоненты Swagger

КомпонентВводВыводПрименимый этап
Swagger EditorРучное написание YAML/JSONДокументация API с предпросмотром в реальном времениЭтап проектирования API
Swagger UIФайл OpenAPIИнтерактивная веб-документацияЭтап разработки/тестирования
Swagger CodegenФайл OpenAPIКлиентский/серверный кодЭтап взаимодействия фронтенда и бэкенда

Схема взаимодействия компонентов:

Swagger Editor（设计API）  
  ↓  
OpenAPI 规范文件（YAML/JSON）  
  ↓  
Swagger UI（展示文档） или  Swagger Codegen（生成代码）

Объяснение основных компонентов Swagger

1. Swagger Editor

Swagger Editor — это браузерный визуальный редактор для написания и предварительного просмотра спецификаций OpenAPI (формат YAML/JSON) в реальном времени.

Swagger Editor обеспечивает подсветку синтаксиса, автодополнение и проверку ошибок.

Функции генерации кода, сохранения и экспорта Swagger Editor теперь интегрированы в SmartBear API Hub. Адрес доступа:https://try.platform.smartbear.com/new-organization。

Сценарии использования:

  • Быстрое создание прототипов API
  • Изучение синтаксиса спецификации OpenAPI

Откройте онлайн-редактор Swagger Editor:https://editor.swagger.io/

Введите следующий код YAML (определяет простую конечную точку GET /users):

Пример

span style="color: green;">
openapi: 3.0.3
информация:
  title: ПРИМЕР Система управления пользователями
  version: 1.0.0
paths:
  /users:
    get:
      summary: Получить список пользователей
      responses:
        '200':
          description: Успешно возвращает список пользователей
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

С правой стороны будет в реальном времени отображаться документация API и интерактивный интерфейс.

Swagger UI

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

Swagger UI автоматически создаёт примеры запросов, модели ответов и интерфейс отладки.

Swagger UI: https://swagger.io/tools/swagger-ui/

Сценарии использования:

  • Обменивайтесь документацией API внутри команды
  • Фронтенд-разработчики отлаживают API

Пример интеграции (с использованием Node.js), установите зависимости:

npm install swagger-ui-express swagger-jsdoc

Создайте файл конфигурации swagger.js:

Пример

const swaggerJSDoc = require('swagger-jsdoc');
const options = {
  определение: {
    openapi: '3.0.0',
    info: { title: 'User API', version: '1.0.0' },
  },
  apis: ['./routes/*.js'], // Сканировать комментарии в файлах маршрутов
};
const swaggerSpec = swaggerJSDoc(options);
module.exports = swaggerSpec;

Подключите UI в Express:

Пример

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerSpec = require('./swagger');

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

Посетите http://localhost:3000/api-docs, чтобы просмотреть документацию.

Swagger Codegen

Swagger Codegen автоматически создает клиентские SDK (например, Java, Python) или заготовки серверного кода (например, Spring, Flask) на основе спецификаций OpenAPI.

Swagger Codegen поддерживает пользовательские шаблоны.

Страница загрузки:https://swagger.io/tools/swagger-codegen/

Сценарии использования:

  • Быстрое создание клиентского кода для вызовов API
  • Автоматизированная разработка серверных интерфейсов

Пример работы (генерация Java-клиента через командную строку), скачайте Swagger Codegen CLI:

wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.35/swagger-codegen-cli-3.0.35.jar -O swagger-codegen-cli.jar

Сгенерировать код:

java -jar swagger-codegen-cli.jar generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -l java \
  -o ./petstore-api-client

Swagger Hub (необязательное расширение)

Swagger Hub — облачная платформа Swagger, обеспечивающая совместное проектирование, управление версиями и размещённую документацию.

Swagger Hub поддерживает командную работу и управление жизненным циклом API.

Сценарии использования:

  • Управление API-проектами корпоративного уровня
  • Распределённые команды, которым нужна онлайн-совместная работа

Адрес доступа:https://swagger.io/api-hub/

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