swagger

Оба подхода имеют свои преимущества и недостатки, и выбор зависит от конкретных требований вашего проекта и предпочтений команды разработчиков. Вот некоторые соображения:

Отдельная страница для каждого микросервиса

Преимущества:

• У каждого микросервиса есть своя собственная документация, что может быть удобным для управления и обслуживания.
• Легче поддерживать и обновлять документацию для каждого сервиса, так как изменения в одном сервисе не влияют на другие.

Недостатки:

Выбор зависит от нескольких моментов, в т.ч. стоит учитывать:
размер вашего проекта, его архитектуру, командные соглашения и личные предпочтения.

На что именно стоит обратить внимание:

Error: [Syntax Error] Expected PlainValue, got '[' in on line

Пишем вместо квадратных скобок дял массива, например:

example={"name": "CUSTOMER_ROLE", "permissions": [1, 3]}

фигурные:

example={"name": "CUSTOMER_ROLE", "permissions": {1, 3}}

то же самое в контексте всей аннотации:

Предположим, что yaml с информацией о метода вы генерировать уже уже научились и теперь нам надо перегнуть его в html.

Наиболее простым способом является (но не самым быстрым и удобным):

1. взять сгенерированный yaml
2. добавить его слева в область кода на https://editor.swagger.io/
3. и далее из главного меню:
   

   Generate Client -> html2

   качаем получившийся html и наслаждаемся)

JsonParseException: Unrecognized token 'openapi'

В ответ на команду:

java -jar swagger-codegen-cli.jar generate -i /var/www/myproject/openapi.yaml -l  php

При этом файл (openapi.yaml), который генератор должен парсить выглядит так:

openapi: 3.0.0
info:
  title: 'API'
  version: 1.0.0
paths:
  /v1/api/campaign-types:
    get:
      operationId: getUserByName
      responses:
        '200':
          description: 'Список типов компаний'

Решение

Ошибка вида:

An exception has been thrown during the rendering of a template [Semantical Error] The annotation ... in class ... was never imported. Did you maybe forget to add a use statement for this annotation? in .... (which is being imported from .../config/routes/annotations.yaml). Make sure annotations are installed and enabled)

Решение

В качестве решения можно использовать в любом стартовом файле проекта ( в symfony 4 можно использовать config/bootstrap.php) код, вида:

Required @OA\Info() not found
Required @OA\PathItem() not found

Добавьте в любой из php-файлов из той папки, которую вы обходите, что-то вроде:

/**
 * @OA\Info(title="My First API", version="0.1")
 */

/**
 * @OA\Get(
 *     path="/api/resource.json",
 *     @OA\Response(response="200", description="An example resource")
 * )
 */

Установка
Возможно, имеет смысл установить как пакет для разработки (dev):

composer require zircote/swagger-php

Работа с паветом
Действуем так:

Swagger -- средство для удобной разработки и просмотра документации к метода REST API.

• Официальный сайт: https://swagger.io/
• Как начать использовать в php-проекте.

Остальные материалы см. по ссылкам ниже.