DEV Community

Discussion on: The state of Laravel-based APIs - a personal research

nilportugues profile image
Nil Portugués Calderó

I'm happy to see my JSON API implementation on the list.

Nice write up.

I can certainly add Swagger doc generation and it was on the works at some point but was unsure if community needed and so my effort to build it.

igorsantos07 profile image
Igor Santos Author

Somewhere during this research (I think it's in Dingo docs) I saw something I completely agree: documenting your API is as important as having it working. APIs don't autocomplete not even in the best IDE, so your end user must be able to read how the API works.

I'm not sure how PITA is to implement Swagger exports, but I guess Blueprint is a much easier target format and might be a good middle-ground there.

Finally, maybe the way to go is to simply show more love for the Dingo integration, as they already do stuff like that :)

BTW, how did you end up seeing my this article? haha

niluspc profile image
Nil 🎗

Yeah I totally agree documentation is a must, but I didn't want to be way too opinanted it because there wasn't a clear winner a couple of years ago. Swagger/OpenAPI is the clear winner for non GraphQL APIs now.

IMHO for PHP zircote/swagger-php is the best option to document using annotations in php doc-blocks without the need of writing the JSON yourself.

I'm still working on API development, currently under NodeJS and Java platforms, so I'm following all API posts and GraphQL posts here at :)

Thread Thread
igorsantos07 profile image
Igor Santos Author

Hahaha cool you ended up here :)

From past experience Swagger seemed really a PITA to get implemented, although being very powerful. Might be just a false impression, tho.

For my current case I ended up going with Postman. Started using it quickly to verify development, then wrote a test or two, then saw docs there... 🤷🏼‍♂️

Thanks for the input!