api_schema_requirements.md

Правила по написанию файлов документации

1. Cтруктура

index.yaml - Основной файл описания api.
В нем описываются все методы апи, а также подключаются компоненты из других файлов.

1.1 Версионирование

Для версиоинирования каждую версию api нужно описать в отдельной папке: v1, v2 и так далее.
В каждой папке должен быть свой собственный index.yaml: пример.
Если директории с версиями отсутствуют index.yaml считается первой версией апи.

2. Правила генерации

• Dto-модели генерируются из компонентов описанных в #/components/schemas или подключенных через $ref в индексном файле. Название класса Dto-модели будет соответствовать названию из спецификации;
• Для названия компонентов отвечающих за request/response нужно в конце добавлять префикс Request/Response;
• В описании каждого эндпоинта обязательно нужно указывать tags - для группировки методов и operationId - для генерации логичных названий у методов;
• Подключение моделей между файлами можно организовать через Remote Reference: https://swagger.io/docs/specification/using-ref/ Пункт '$ref Syntax'
• Для описания enum используем расширение openapi-generator;
• В #/components/schemas допустимо выносить модели, которые нигде не используются, но хотелось бы получить при генерации под них класс.