Swagger Codegen (генерация кода)

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

Swagger в основном включает:

  • Swagger Editor: браузерный редактор, позволяющий писать спецификации OpenAPI
  • Swagger UI: визуальный интерфейс документации API, позволяющий разработчикам интерактивно изучать API
  • Swagger Codegen: автоматически генерирует клиентский код и серверные заглушки на основе спецификации OpenAPI

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

OpenAPI позволяет как людям, так и компьютерам обнаруживать и понимать возможности сервиса без необходимости доступа к исходному коду или дополнительной документации.


Swagger Codegen (генерация кода)

Подготовка окружения

Прежде чем начать, убедитесь, что в вашей системе установлено следующее:

  • Java 8+
  • Maven (для проектов на Java)
  • Git (для получения исходного кода)

Установите Swagger Codegen:

# 方法1: 使用homebrew (macOS)
brew install swagger-codegen

# 方法2: 从GitHub下载JAR文件
wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.36/swagger-codegen-cli-3.0.36.jar -O swagger-codegen-cli.jar
java -jar swagger-codegen-cli.jar help

Сгенерировать клиентский SDK

Генерация Java-клиента

Используйте Petstore API в качестве примера для генерации Java-клиента:

# 使用命令行工具
swagger-codegen generate -i https://petstore.swagger.io/v2/swagger.json -l java -o ./java-client

# 或使用JAR文件
java -jar swagger-codegen-cli.jar generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -l java \
  -o ./java-client

Структура сгенерированного клиентского SDK:

java-client/
├── pom.xml                  # Maven项目文件
├── README.md                # 说明文档
├── src/
│   ├── main/
│   │   ├── java/           # 生成的Java代码
│   │   └── resources/      # 配置文件
│   └── test/               # 测试代码
└── .gitignore

Использование сгенерированного Java-клиента:

Пример

import io.swagger.client.*;
import io.swagger.client.auth.*;
import io.swagger.client.model.*;
import io.swagger.client.api.PetApi;

public class Example {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
       
        // Настройка аутентификации по API-ключу
        ApiKeyAuth apiKey = (ApiKeyAuth) defaultClient.getAuthentication("api_key");
        apiKey.setApiKey("ВАШ API-КЛЮЧ");
       
        PetApi apiInstance = new PetApi();
        try {
            Pet result = apiInstance.getPetById(789L);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Исключение при вызове PetApi#getPetById");
            e.printStackTrace();
        }
    }
}

Генерация Python-клиента

Сгенерируйте Python-клиент:

swagger-codegen generate -i https://petstore.swagger.io/v2/swagger.json -l python -o ./python-client

Пример использования Python-клиента:

Пример

import swagger_client
from swagger_client.rest import ApiException

# Создать экземпляр API-клиента
api_instance = swagger_client.PetApi()
api_client = api_instance.api_client

# Установить ключ API
api_client.configuration.api_key['api_key'] = 'YOUR_API_KEY'

try:
    # Получить питомца с указанным ID
    pet = api_instance.get_pet_by_id(pet_id=789)
    print(pet)
except ApiException as e:
    print("Исключение при вызове PetApi->get_pet_by_id: %s\n" % e)

Поддержка других языков

Swagger Codegen поддерживает множество языков и фреймворков, включая, но не ограничиваясь:

  • JavaScript/TypeScript (Node.js, Angular, React и т. д.)
  • Ruby
  • PHP
  • C#/.NET
  • Go
  • Swift
  • Kotlin
  • Scala

Просмотреть список поддерживаемых языков:

swagger-codegen langs

Сгенерировать код заглушки сервера

Генерация кода сервера Spring

Сгенерировать заглушку сервера Spring Boot:

swagger-codegen generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -l spring \
  -o ./spring-server

Структура сгенерированного кода сервера Spring:

spring-server/
├── pom.xml                  # Maven项目文件
├── README.md                # 说明文档
├── src/
│   ├── main/
│   │   ├── java/           # 控制器接口和模型类
│   │   └── resources/      # 配置文件和静态资源
│   └── test/               # 测试代码
└── .gitignore

Реализуйте сгенерированный интерфейс контроллера:

Пример

@Controller
public class PetApiController implements PetApi {
    @Override
    public ResponseEntity<Pet> getPetById(Long petId) {
        // Реализуйте логику API
        Pet pet = new Pet();
        pet.setId(petId);
        pet.setName("sample pet");
        pet.setStatus(Pet.StatusEnum.AVAILABLE);
        return ResponseEntity.ok(pet);
    }
}

Генерация кода сервера Node.js

Сгенерируйте код сервера Node.js:

swagger-codegen generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -l nodejs-server \
  -o ./nodejs-server

Пример использования для сервера Node.js:

Пример

// Реализуйте бизнес-логику в сгенерированном файле сервиса
module.exports.getPetById = function(petId) {
  return new Promise(function(resolve, reject) {
    var examples = {};
    examples['application/json'] = {
      "id": petId,
      "name": "sample pet",
      "status": "available"
    };
    resolve(examples[Object.keys(examples)[0]]);
  });
}

OpenAPI Generator: продвинутый уровень

OpenAPI Generator против Swagger Codegen

OpenAPI Generator — это форк Swagger Codegen, который начал независимую разработку в 2018 году. Его основные преимущества включают:

  • Более активная поддержка сообщества
  • Более широкая поддержка шаблонов
  • Улучшенная поддержка OpenAPI 3.0
  • Больше параметров конфигурации и возможностей настройки

Установите OpenAPI Generator:

# 使用npm安装
npm install @openapitools/openapi-generator-cli -g

# 使用Homebrew安装
brew install openapi-generator

# 下载JAR文件
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.0.1/openapi-generator-cli-6.0.1.jar -O openapi-generator-cli.jar

Установка и базовое использование

Базовое использование:

# 显示帮助信息
openapi-generator help

# 生成Java客户端
openapi-generator generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -g java \
  -o ./java-client

# 列出支持的生成器
openapi-generator list

Пользовательские шаблоны

Основы шаблонов

OpenAPI Generator использует шаблонизатор Mustache. Чтобы настроить генерируемый код, необходимо:

  1. Получить шаблоны по умолчанию
  2. Изменить шаблоны под свои потребности
  3. Сгенерировать код с использованием пользовательских шаблонов

Создание пользовательских шаблонов<
# 使用JAR文件获取特定语言的模板
java -jar openapi-generator-cli.jar author template \
  -g java \
  -o ./custom-templates/java

Пример файла шаблона (api.mustache для Java):

{{>licenseInfo}}
package {{package}};

{{#imports}}import {{import}};
{{/imports}}

{{#operations}}
public interface {{classname}} {
    {{#operation}}
    {{#summary}}
    /**
     * {{summary}}
     * {{/summary}}
     {{#notes}}
     * {{notes}}
     {{/notes}}
     */
    {{#returnType}}{{returnType}} {{/returnType}}{{^returnType}}void {{/returnType}}{{operationId}}({{#allParams}}{{dataType}} {{paramName}}{{^-last}}, {{/-last}}{{/allParams}});
    
    {{/operation}}
}
{{/operations}}

Применить шаблон для генерации кода

Генерировать код с использованием пользовательских шаблонов:

openapi-generator generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -g java \
  -o ./java-client-custom \
  -t ./custom-templates/java

Пользовательская конфигурация

Глобальные параметры конфигурации

OpenAPI Generator поддерживает различные глобальные параметры конфигурации:

openapi-generator generate \
  -i spec.yaml \
  -g java \
  -o output \
  --api-package com.example.api \
  --model-package com.example.model \
  --package-name com.example \
  --git-repo-id my-repo \
  --git-user-id my-username

Конфигурация для конкретного языка

У разных генераторов есть свои собственные специфические параметры конфигурации:

# Java客户端生成器的特定选项
openapi-generator generate \
  -i spec.yaml \
  -g java \
  -o output \
  --library retrofit2 \
  --java8 true \
  --use-rx-java true

Использование файлов конфигурации

Вы можете создать файл конфигурации, чтобы сохранить общие настройки:

Файл config.json

{
  "artifactId": "petstore-client",
  "groupId": "com.example",
  "library": "retrofit2",
  "apiPackage": "com.example.api",
  "modelPackage": "com.example.model",
  "invokerPackage": "com.example.client",
  "dateLibrary": "java8",
  "java8": true
}

Использование файла конфигурации:

openapi-generator generate \
  -i spec.yaml \
  -g java \
  -o output \
  -c config.json

Практические примеры проектов

Проектирование API с нуля

Спроектируйте свой API с помощью Swagger Editor:

  1. Посетитеhttps://editor.swagger.io/
  2. Создайте файл спецификации OpenAPI:

Пример

openapi: 3.0.0
информация:
  title:API управления продуктами
  version: 1.0.0
  description:RESTful API для управления продуктами
servers:
  - url: https://api.example.com/v1
paths:
  /products:
    get:
      summary:Получить список продуктов
      responses:
        '200':
          description:Успешно
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
    post:
      summary:Создать новый продукт
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductInput'
      responses:
        '201':
          description:Создание выполнено успешно
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
  /products/{productId}:
    get:
      summary:Получить отдельный продукт
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description:Успешно
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
components:
  schemas:
    Продукт:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        price:
          type: number
        category:
          type: string
        createdAt:
          type: string
          format: date-time
    ProductInput:
      type: object
      required:
        - name
        - price
      properties:
        name:
          type: string
        price:
          type: number
        category:
          type: string

Генерация полного кода проекта

Сгенерируйте полный проект на основе разработанной спецификации API:

  1. Сохраните спецификацию API какproduct-api.yaml
  2. Сгенерируйте код фронтенда и бэкенда:
# 生成Spring Boot服务端
openapi-generator generate \
  -i product-api.yaml \
  -g spring \
  -o ./product-service \
  --additional-properties=java8=true,dateLibrary=java8

# 生成React前端
openapi-generator generate \
  -i product-api.yaml \
  -g typescript-fetch \
  -o ./product-frontend \
  --additional-properties=supportsES6=true,npmName=product-api-client

Распространённые проблемы и решения

  1. Сгенерированный код не компилируется

    • Убедитесь, что спецификация OpenAPI соответствует стандартам
    • Проверьте пользовательские шаблоны на наличие синтаксических ошибок
    • Обновите до последней версии генератора
  2. Пользовательские шаблоны не применяются

    • Убедитесь, что путь к шаблону указан правильно
    • Проверьте, что имя файла шаблона совпадает с именем исходного шаблона
    • Используйте абсолютные пути вместо относительных
  3. В сгенерированном коде отсутствуют некоторые возможности

    • Проверьте, полностью ли спецификация OpenAPI определяет требуемую функциональность
    • Убедитесь, что используются правильный генератор и параметры конфигурации
    • Рассмотрите возможность использования пользовательских шаблонов для добавления дополнительной функциональности
  4. Сгенерированный код несовместим с существующими проектами

    • Используйте параметры конфигурации для настройки имён пакетов и соглашений об именовании
    • Настройте стиль кода с помощью пользовательских шаблонов
    • Рассмотрите возможность генерации только интерфейсов API и ручной реализации конкретной логики

Расширенные возможности и лучшие практики

Управление версиями

Рекомендации по управлению версиями API:

  1. Четко указывайте номер версии в спецификации OpenAPI
  2. Используйте семантическое версионирование (SemVer)
  3. Используйте разные базовые пути для разных версий API
  4. Сохраняйте файлы спецификации для всех версий

Интеграция CI/CD

Интегрируйте генерацию кода в конвейер CI/CD:

Пример

# Пример рабочего процесса GitHub Actions
name: Сгенерировать клиент API

на:
  push:
    paths:
      - 'api-specs/**'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
     
      - name: Настроить JDK
        uses: actions/setup-java@v2
        with:
          java-version: '11'
         
      - name: Установить OpenAPI Generator
        run: npm install @openapitools/openapi-generator-cli -g
       
      - name: Сгенерировать клиент
        run: |
          openapi-generator generate \
            -i api-specs/product-api.yaml \
            -g typescript-fetch \
            -o ./generated-client
           
      - name: Зафиксировать и отправить
        run: |
          git config --global user.name 'GitHub Actions'
          git config --global user.email 'actions@github.com'
          git add ./сгенерированный-клиент
          git commit -m "Автоматически сгенерировать API-клиент"
          git push

Рекомендации для корпоративных приложений

Для проектов корпоративного уровня:

  1. Централизованно управляйте спецификациями API

    • Используйте выделенный репозиторий Git для управления спецификациями API
    • Внедрите процесс проверки кода для обеспечения качества
  2. Создайте руководство по стилю для сгенерированного кода

    • Создайте единые соглашения об именовании
    • Определите стандарты обработки ошибок
    • Разработайте единый подход к обработке аутентификации
  3. Смешивайте сгенерированный код и код, написанный вручную

    • Генерируйте базовый каркас и модели данных
    • Реализуйте сложную бизнес-логику вручную
    • Используйте паттерн адаптера для изоляции сгенерированного кода и кода, написанного вручную
  4. Рассмотрите микросервисную архитектуру

    • Поддерживайте независимые спецификации API для каждого микросервиса
    • Используйте API-шлюз для унификации внешних интерфейсов
    • Реализуйте клиентский код между сервисами с помощью генерации кода
Другие расширения