php Как начать использовать Swagger для генерации документации. Иструкция по шагам

Действуем так:

  1. Ставим какой-нибудь пакет, который умеет генерировать разметку swagger на основании аннотаций к php-коду, здесь и далее мы будем использовать zircote/swagger-php .
  2. После чего переходим в командой строке в корень php-проекта, и выполняем команду вроде:
     ./vendor/bin/openapi -o openapi.yaml src/Controller/

    (в моем случае код лежит именно в src/Controller/)
    Если вы ещё не писали аннотации, команда может завершиться ошибкой вроде этой, тогда вам надо добавить в один из php-классов (напр. в начале файла) аннотации вроде:

    /**
     * @OA\Info(title="Пример доки к API", version="0.1")
     */
     
    /**
     * @OA\Get(
     *     path="/api/resource.json",
     *     @OA\Response(response="200", description="Чтобы как-то начать ;)")
     * )
     */
    
  3. После того, как вы добавили аннотацию, запустите команду заново и посмотрите на результат в файле openapi.yaml - он должен был появиться в корне проекта.
    Отрисовать результат можно, например, в онлайн-редакторе своггера. (если вы работаете с symfony или чем-то подобным, то может быть придется включить игнорирование аннотаций Open API)
  4. Также можно генерировать html документацию на локальной машине (или собственном сервере, см. доступные способы тут).

Источники: