Skip to content

Latest commit

 

History

History
60 lines (52 loc) · 4.67 KB

api_schema_requirements.md

File metadata and controls

60 lines (52 loc) · 4.67 KB
Raw

Требования к openapi файлам и нюансы генерации

Требования к структуре

  • Все yaml файлы должны располагаться либо в поддиректориях v1, v2,... vN директории указанной в конфиге в поле apidoc_dir.
  • Входной точкой для спецификации каждой версии api должен быть файл index.yaml
  • Каждая Enum модель должна находиться в отдельном файле с названием {enum_name_in_snake_case}_enum.yaml. Эти enumы при генерации подвергаются патчингу

Требования к содержанию openapi файлов

  • Все эндпоинты должны быть описаны в index.yaml
  • Для каждого эндпоинта должны быть указаны tags и operationId.
  • Для request/request модели необходимо добавлять Request/Response в конец названия.
  • Не должны быть $ref ссылки на что-либо не лежащее в той же директории
  • (?) Все объекты запросов и ответов выносятся в отдельные файлы и подключаются напрямую.

Нюансы генерации

Важно понимать, что генератором генерируются классы только из

  • #/components/schemas/Model
  • Отдельных файлов, которые подключены через $ref в индексный файл
    Причем название будущего класса будет соответствовать названию файла (транслированному в CamelCase) или названию схемы.
  • В #/components/schemas допустимо выносить модели, которые нигде не используются, но хотелось бы получить при генерации под них класс.

Enum

C enum есть 2 проблемы

  1. По сути это свойство с типом integer/string. Но генератором оно генерируется как отдельный класс, из-за того что мы выносим перечисление отдельным файл и потом подключаем везде. И соответственно требует в свойствах в качестве значения этот класс. А мы не может число определить как этот сгенерированный класс.
  2. При числовых перечисления класс генерируется с синтаксической ошибкой OpenAPITools/openapi-generator#1475

Для решения этих проблем

  1. Под каждый enum создаём файл с названием {banana}_enum.yaml
  2. Содержимое файла должно быть следующего вида:
type: number
description: >
    Роли. Расшифровка значений:
     * Роли админки:
     * `101` - Супер-администратор
     * `102` - Администратор
     * `113` - Оператор колл-центра
     * `115` - Администратор магазина
     * Роли витрины:
     * `403` - Неавторизованный пользователь
enum:
    - 101 # ADMIN__SUPER | Супер-администратор
    - 102 # ADMIN__ADMIN | Администратор
    - 113 # ADMIN__OMS_CALL_CENTER | Оператор колл-центра
    - 115 # ADMIN__MERCHANT_ADMINISTRATOR | Администратор магазина
    - 403 # SHOWCASE__GUEST | Неавторизованный пользователь

Важно заполнение свойства enum. Необходимо четко придерживаться шаблона выше: - <value> # <name> | <comment>. Здесь value - значение перечисления, name - название, comment - комментарий в одну строку.
3. В index.yaml подключаем наш файл в качестве компонента с названием {Banana}Enum и нигде не используем
4. Во всех местах, где наше перечисление должно быть свойством (например order.banana_id), то указываем banana_id как

banana_id:
  description: Описание поля
  allOf:
    - type: integer
    - $ref: './banana_enum.yaml'