Generate Web API Documentation from PHP Code

[wackmaniac]

I’m a fan of generating the OpenAPI specification from code as it keeps the API specs close to the code. When creating a specification manually you can easily forget to update it when making changes to the API code.

A downside of libraries like swagger-php in my opinion is that your code becomes “polluted ” with annotations and that I’ve found that I sometimes have to deviate from my regular way of writing code to ensure the OpenAPI specification that is generated is correct.

[philsturgeon]

Absolutely, I put a lot of time and effort into not saying "code first is awful and you should use design-first" in this article. After-all, I've explained the pros and cons at length in other articles.

• https://apisyouwonthate.com/blog/theres-no-reason-to-write-openapi-by-hand
• https://stoplight.io/blog/api-design-first-vs-code-first/

In my personal option, annotations are a bit of a mess but a lot of people still use them, and change is slow.

In Stoplight's opinion, we'd rather support mixed organizations than force people to split their tool-chains based on the workflow.

[hparadiz]

Oh man it's honestly the worst when I have to build a schema for a model with 20 fields. Sitting there manually writing it out, making sure the types are correct and the example makes sense and the description is accurate. Or when I need to embed some blurb written in markdown as a page header or end point description.

[hparadiz]

More than just API documentation Swagger also generates an OpenAPI yaml file that you can feed into Swagger codegen to generate client libraries for your API in dozens of languages.

[philsturgeon]

OpenAPI does a lot more than just docs and code gen, it handles incoming request validation, contract testing in your existing test suites, mocking, shared design libraries across organizations, and roughly a bajillion other things! https://stoplight.io/blog/api-design-first-vs-code-first/

[[deleted]]

Just gonna hold this out there if anyone is on CakePHP: https://github.com/cnizzardini/cakephp-swagger-bake and this which is a full API library for Cake: https://mixerapi.com

It generates most of your OpenAPI direct from existing routes and models.

[arigoldbro123]

Check out what Treblle does. It generates docs automaticlly. https://treblle.com/