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.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-клиента:
Пример
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
Реализуйте сгенерированный интерфейс контроллера:
Пример
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. Чтобы настроить генерируемый код, необходимо:
- Получить шаблоны по умолчанию
- Изменить шаблоны под свои потребности
- Сгенерировать код с использованием пользовательских шаблонов
Создание пользовательских шаблонов<# 使用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:
- Посетитеhttps://editor.swagger.io/
- Создайте файл спецификации OpenAPI:
Пример
информация:
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:
- Сохраните спецификацию API как
product-api.yaml - Сгенерируйте код фронтенда и бэкенда:
# 生成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
Распространённые проблемы и решения
-
Сгенерированный код не компилируется
- Убедитесь, что спецификация OpenAPI соответствует стандартам
- Проверьте пользовательские шаблоны на наличие синтаксических ошибок
- Обновите до последней версии генератора
-
Пользовательские шаблоны не применяются
- Убедитесь, что путь к шаблону указан правильно
- Проверьте, что имя файла шаблона совпадает с именем исходного шаблона
- Используйте абсолютные пути вместо относительных
-
В сгенерированном коде отсутствуют некоторые возможности
- Проверьте, полностью ли спецификация OpenAPI определяет требуемую функциональность
- Убедитесь, что используются правильный генератор и параметры конфигурации
- Рассмотрите возможность использования пользовательских шаблонов для добавления дополнительной функциональности
-
Сгенерированный код несовместим с существующими проектами
- Используйте параметры конфигурации для настройки имён пакетов и соглашений об именовании
- Настройте стиль кода с помощью пользовательских шаблонов
- Рассмотрите возможность генерации только интерфейсов API и ручной реализации конкретной логики
Расширенные возможности и лучшие практики
Управление версиями
Рекомендации по управлению версиями API:
- Четко указывайте номер версии в спецификации OpenAPI
- Используйте семантическое версионирование (SemVer)
- Используйте разные базовые пути для разных версий API
- Сохраняйте файлы спецификации для всех версий
Интеграция CI/CD
Интегрируйте генерацию кода в конвейер CI/CD:
Пример
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
Рекомендации для корпоративных приложений
Для проектов корпоративного уровня:
-
Централизованно управляйте спецификациями API
- Используйте выделенный репозиторий Git для управления спецификациями API
- Внедрите процесс проверки кода для обеспечения качества
-
Создайте руководство по стилю для сгенерированного кода
- Создайте единые соглашения об именовании
- Определите стандарты обработки ошибок
- Разработайте единый подход к обработке аутентификации
-
Смешивайте сгенерированный код и код, написанный вручную
- Генерируйте базовый каркас и модели данных
- Реализуйте сложную бизнес-логику вручную
- Используйте паттерн адаптера для изоляции сгенерированного кода и кода, написанного вручную
-
Рассмотрите микросервисную архитектуру
- Поддерживайте независимые спецификации API для каждого микросервиса
- Используйте API-шлюз для унификации внешних интерфейсов
- Реализуйте клиентский код между сервисами с помощью генерации кода