Перейти к содержимому
Последнее обновление

Спецификация OpenAPI

API Vilna полностью документирован с использованием спецификации OpenAPI 3.1, что позволяет автоматически генерировать клиенты и интегрироваться с популярными инструментами для работы с API.

Доступ к спецификации

Спецификация OpenAPI доступна по адресу:

  • Справочник API: /apis/spec.yaml
  • Формат: OpenAPI 3.1
  • Схема: JSON Schema Draft 2020-12

Генерация клиентов

OpenAPI Generator

Генерируйте клиентские библиотеки для предпочитаемого языка программирования с помощью OpenAPI Generator:

# Установка OpenAPI Generator
npm install -g @openapitools/openapi-generator-cli

# Генерация клиента (пример для Python)
openapi-generator-cli generate \
  -i path/to/spec.yaml \
  -g python \
  -o ./vilna-python-client

Поддерживаемые языки включают Python, JavaScript, TypeScript, Go, Java, C#, PHP, Ruby и многие другие.

Swagger Codegen

Альтернативная генерация клиента с использованием Swagger Codegen:

# Генерация клиента (пример для Java)
swagger-codegen generate \
  -i path/to/spec.yaml \
  -l java \
  -o ./vilna-java-client

Инструменты тестирования API

Swagger UI

Используйте Swagger UI для визуализации и взаимодействия с API:

  1. Импортируйте спецификацию OpenAPI
  2. Изучите доступные endpoints
  3. Тестируйте API-вызовы прямо из браузера
  4. Просматривайте схемы запросов и ответов

Postman

Импортируйте спецификацию в Postman:

  1. Откройте Postman
  2. Нажмите "Import" → "File"
  3. Выберите файл спецификации OpenAPI
  4. Postman создаст коллекцию со всеми endpoints
  5. Настройте ваш API-ключ в переменных коллекции

Insomnia

Используйте Insomnia для отладки API:

  1. Создайте новый Document в Insomnia
  2. Импортируйте спецификацию OpenAPI
  3. Настройте аутентификацию
  4. Тестируйте endpoints с автодополнением

Инструменты генерации кода

TypeScript типы

Генерируйте TypeScript типы из спецификации OpenAPI:

# Используя openapi-typescript
npx openapi-typescript path/to/spec.yaml --output vilna-types.ts

Узнайте больше на openapi-typescript.

Валидация API

Валидируйте запросы и ответы в соответствии со спецификацией OpenAPI:

Mock сервер

Создайте mock сервер для разработки и тестирования:

# Используя Prism
npm install -g @stoplight/prism-cli
prism mock path/to/spec.yaml

Узнайте больше о Prism Mock Server.

Генерация документации

Генерируйте документацию API из спецификации:

Интеграция с IDE

VS Code

Установите расширение OpenAPI (Swagger) Editor для:

  • Подсветки синтаксиса
  • Автодополнения
  • Валидации
  • Предпросмотра

JetBrains IDEs

Используйте встроенный OpenAPI Specifications plugin для:

  • Генерации кода
  • Навигации по endpoints
  • Тестирования запросов

Лучшие практики

  1. Контроль версий: Всегда указывайте версию API при генерации клиентов
  2. Валидация: Валидируйте вашу реализацию в соответствии со спецификацией
  3. Обновления: Перегенерируйте клиенты при обновлении спецификации API
  4. Кастомные шаблоны: Используйте кастомные шаблоны для генерируемого кода при необходимости
  5. Тестирование: Используйте спецификацию для контрактного тестирования

Дополнительные ресурсы

Спецификация OpenAPI является источником истины для Vilna API. Все инструменты и сгенерированные клиенты должны основываться на этой спецификации.

Предыдущая страница
Следующая страница