Consider using swagger-php to automatically generated OpenAPI docs

[acelaya]

https://zircote.github.io/swagger-php/guide/annotations.html

Back in the day, I made a conscious decision of manually writing the swagger/open API spec.

The reason is that I always felt tooling that generates them automatically, frequently requires annotating your source code with API docs info that pollutes it and mixes/spreads docs inside your source code.

However, very often I find myself almost forgetting to document changes due to the docs being separated from the source code, or even worried that I might make a mistake and document something incorrectly and not matching the actual behavior.

Because of this I want to do a POC, using swagger-php to document one endpoint and see how it feels, what are the pros and cons of both options and try to decide if manual documentation is still the way to go or not.

• Document the decision on an architectural decision record.

[webysther]

This will be great, more easy to import as collection on postman because the open api 3.

[acelaya]

This will be great, more easy to import as collection on postman because the open api 3.

The project already provides OAS specs. This ticket is just to investigate a different approach to generate them.

You can find spec definitions for every version here https://github.com/shlinkio/shlink-open-api-specs

These are all fed to https://api-spec.shlink.io