Как лучше описывать документацию API в PHP 8.1 через аннотации или атрибуты?

Question

[Кирилл]

Нужно написать API, за основу взял чистую симфони 6.4 - автогенерацию документации не использую, т.к. вручную хочу это все контролировать.

И здесь я встал перед выбором, что использовать для описания API, аннотации или атрибуты. С использованием аннотаций имеется куча материалов, и множество примеров в официальной документации Swagger-PHP, а также на разных блогах, а вот с атрибутами как-то не очень.

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

С одной стороны, чтобы уложиться в сроки, лучше бы использовать аннотации, т.к. достаточно много примеров, мануалов, но с другой - из-за введения атрибутов возможно в будущем аннотации будут выпиливать из Swagger-PHP, а переписывать потом аннотации на атрибуты не особо захочется.

Поэтому вопрос к знатокам, как тут быть? И если лучше использовать атрибуты, скиньте пожалуйста какие-нибудь толковые мануалы по описанию апишек, т.к. с атрибутами я вижу только в репозитории Swagger-PHP несколько примеров.

Answer 1

[BoShurik]

Аттрибуты. Использование один в один, они даже наследуются от аннотаций

namespace OpenApi\Attributes;

#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
class Get extends \OpenApi\Annotations\Get

Comments

[Кирилл]

Спасибо за ответ) Буду в них погружаться)))

Answer 2

[Виктор Кожухарь]

Используйте атрибуты.
Да, на данный конкретный момент документации по аннотациям больше, но, во-первых, как верно заметил уважаемый BoShurik , атрибуты почти всегда полностью соответствуют аннотациям в плане параметров, а, во-вторых, сообщество PHP целенаправленно идёт в сторону использования атрибутов, и однажды, когда-нибудь, при апгрейде вам прямо придётся переписать аннотации на атрибуты, потому что какая-то новая версия откажется от аннотаций.

Comments

[Кирилл]

Согласен, и вы подтвердили мои опасения) Спасибо за ответ)