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

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

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

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

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


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

### OpenAPI Generator

Генерируйте клиентские библиотеки для предпочитаемого языка программирования с помощью [OpenAPI Generator](https://openapi-generator.tech/):


```bash
# Установка 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 и [многие другие](https://openapi-generator.tech/docs/generators).

### Swagger Codegen

Альтернативная генерация клиента с использованием [Swagger Codegen](https://swagger.io/tools/swagger-codegen/):


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

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

### Swagger UI

Используйте [Swagger UI](https://swagger.io/tools/swagger-ui/) для визуализации и взаимодействия с API:

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


### Postman

Импортируйте спецификацию в [Postman](https://www.postman.com/):

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


### Insomnia

Используйте [Insomnia](https://insomnia.rest/) для отладки API:

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


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

### TypeScript типы

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


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

Узнайте больше на [openapi-typescript](https://github.com/drwpow/openapi-typescript).

### Валидация API

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

- **Node.js:** [express-openapi-validator](https://github.com/cdimascio/express-openapi-validator)
- **Python:** [openapi-core](https://github.com/p1c2u/openapi-core)
- **Go:** [kin-openapi](https://github.com/getkin/kin-openapi)


## Mock сервер

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


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

Узнайте больше о [Prism Mock Server](https://stoplight.io/open-source/prism).

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

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

- **ReDoc:** [ReDoc](https://github.com/Redocly/redoc)
- **Slate:** [widdershins](https://github.com/Mermade/widdershins) + [Slate](https://github.com/slatedocs/slate)
- **MkDocs:** [mkdocs-openapi](https://github.com/blueswen/mkdocs-openapi)


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

### VS Code

Установите расширение [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) для:

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


### JetBrains IDEs

Используйте встроенный [OpenAPI Specifications plugin](https://www.jetbrains.com/help/idea/openapi.html) для:

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


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

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


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

- [OpenAPI Initiative](https://www.openapis.org/)
- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
- [JSON Schema](https://json-schema.org/)
- [API Tools Directory](https://openapi.tools/)


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