search

zircote / swagger-php

A php swagger annotation and parsing library
http://zircote.github.io/swagger-php/
Apache License 2.0
5.08k stars 933 forks source link

[Feature]: Append "tags" list via Operation attribute #1610

Closed mazumba closed 3 months ago

mazumba commented 3 months ago

We use vacuum to validate our swagger file and for the api to be valid, the list of used tags is required.

tags:
  - name: Some Tag
    description: Description of said tag

If we only define the tags within a controller attribute, the endpoints are still correctly grouped by their tags but no tags list is added to the api-docs file.

#[OA\Get(
        operationId: 'uniqueEndpointId' ,
        description: 'Explanation for the endpoint in detail',
        summary: 'Explanation for the endpoint in short',
        tags: ['Some Tag'],
        ...
)]

My proposal now is to always add the tags list to the api-docs file, whenever the tags parameter is used in any Operation attribute. And when someone wants to add a description to a tag, the Tag attribute can be used as it already is.

mazumba-nx commented 3 months ago

Thank you! 🔥

Flightfreak commented 2 months ago

This has broken our API docs by Redocly. I'm not sure yet why but for now we're unsetting the tags property before we save it. unset($openapi->tags);

DerManoMann commented 2 months ago

This has broken our API docs by Redocly. I'm not sure yet why but for now we're unsetting the tags property before we save it. unset($openapi->tags);

Interesting - if you ever find out let me know. The latest change does remove unused ones - maybe that is the issue?