OpenApiGenerator — или как мы генерируем документацию для 3k сервисов API на PHP без погружения в openapi

[mvs]

Брр, а чем swagger-php не угодил? Он же легко и просто генерит спеку на основе типизированных аттрибутов (с аннотациями сложнее).

У нас каждая новая версия API - это отдельный модуль yii2, контроллеры которого наследуются от контроллеров предыдущей версии;

Т.е. сейчас, условно, на 20-й версии у каждого контроллера 19 предков?

[wapmorgan]

На момент старта работы над генератором (середина 2020-го) была версия zircote/swagger-php 3.0.5, в которой поддержки атрибутов не было, как и самих атрибутов в стабильной версии языка (php 8 ещё не вышла).

на 20-й версии у каждого контроллера 19 предков

Верно.

[michael_v89]

Мы недавно сделали похожую штуку на основе zircote/swagger-php с дополнительной обработкой. Входные и выходные типы берутся из кода с помощью рефлексии, по аналогии с библиотекой GraphQLite для GraphQL. Для других кодов ответа используется специальный класс HttpException и аннотация из zircote/swagger-php.

class SomeController {
  #[Post(...)]
  #[OA\Response(401, 'Unauthorized')]
  public function someAction(#[Body] RequestDTO $requestDto): ResponseDTO
  {
    if (!$this->checkAccess()) {
      throw new HttpException('Not allowed', 401);
    }

    return new ResponseDTO(...);
  }
}

#[OA\Schema]
class RequestDTO {
  ...
}

#[OA\Schema]
class ResponseDTO {
  ...
}