Remote developer with 17+ years of experience. Mostly worked with PHP and with a passion for REST APIs and front-end interfaces, UX and DX - consequentially working also with React and Svelte.
Location
Rio de Janeiro, Brazil
Education
Universidade Estácio de Sá / Dalhousie University
Work
Remote full-stack developer @ eHungry; past Toptal freelancer
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
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 dev.to :)
Remote developer with 17+ years of experience. Mostly worked with PHP and with a passion for REST APIs and front-end interfaces, UX and DX - consequentially working also with React and Svelte.
Location
Rio de Janeiro, Brazil
Education
Universidade Estácio de Sá / Dalhousie University
Work
Remote full-stack developer @ eHungry; past Toptal freelancer
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!
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
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.
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
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 dev.to :)
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!