Abills Developer
Child pages
  • Реализация OpenAPI (Swagger)
Skip to end of metadata
Go to start of metadata

Доступно с 1.20.00

Наша система имеет некоторые надстройки, реализации сверх стандарта OpenAPI (Swagger) вследствии модульности системы.

Принцип работы

Файловая структура OpenAPI для ядра и модулей описана здесь

При запуске misc/api/generate_docs.pl, берутся за основу файлы user.yaml и admin.yaml (для USER и ADMIN API сооветственно)

И проводится поиск за параметрами $ref, которые ведут к частям OpenAPI тех или иных субмодулей ядра и модулей системы.
За ними постепенно вставляется содержимое, которое потом генерируется в bundle_user.yaml и bundle_admin.yaml.

На основе файлов и их названия которые находятся в /schema/ (например: Abills/modules/Portal/Api/swagger/admin/schemas/article.yaml)
Будут генерироваться нативные #/components/schemas/* в бандлах (например: #/components/schemas/PortalArticle)

Примеры

пути к файлам
paths:
  $ref: "./user/user/paths.yaml"
  $ref: "../../Abills/modules/Internet/Api/swagger/user/paths.yaml"
  $ref: "../../Abills/modules/Iptv/Api/swagger/user/paths.yaml"
  $ref: "../../Abills/modules/Msgs/Api/swagger/user/paths.yaml"
  $ref: "../../Abills/modules/Abon/Api/swagger/user/paths.yaml"
  $ref: "../../Abills/modules/Paysys/Api/swagger/user/paths.yaml"
  $ref: "./user/config/paths.yaml"
  $ref: "./user/contacts/paths.yaml"
  $ref: "./user/holdup/paths.yaml"
  $ref: "./user/services/paths.yaml"
  $ref: "./user/bots/paths.yaml"
  $ref: "../../Abills/modules/Portal/Api/swagger/user/paths.yaml"
paths.yaml модуля Portal
/user/portal/menu:
  $ref: "./paths/portal.yaml"
/user/portal/news:
  $ref: "./paths/news.yaml"
/user/portal/news/{id}:
  $ref: "./paths/newsId.yaml"

Рекомендации

  1. Не оставляйте схемы в admin.yaml или user.yaml.
    Старайтесь их распределять по папкам файловой структуры OpenAPI, чтобы дать возможность нативно сгенерировать объекты.
  2. Старайтесь в schemas которые обозначают список, ссылаться файлом на единичный экземпляр.
    Это позволит не редактировать .yaml 2 или более раза.
  3. Старайтесь не писать схемы в самом определении пути, а делить их по-компонентно.
  4. Не забывайте проверять OpenAPI на валидность с помощью Swagger Editor.
  • No labels