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

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

composer require zircote/swagger-php

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

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 документацию на локальной машине (или собственном сервере, см. доступные способы тут).

Источники:

• https://kurapov.ee/rus/technology/integr...
• Документация по zircote/swagger-php: https://zircote.github.io/swagger-php/
• Как начать с zircote/swagger-php: https://github.com/zircote/swagger-php/b...