Ranter
Join devRant
Do all the things like
++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatar
Sign Up
Pipeless API
From the creators of devRant, Pipeless lets you power real-time personalized recommendations and activity feeds using a simple API
Learn More
Comments
-
Hel8y3375yFor a while we have been using JSON schemas to document our API endpoints. Those schemas are used to validate input and functional / accaptance tests use the JSON schemas to validate the the output of every endpoint. And the examples in the JSON schemas are validated against the schema itself, to make sure the documentation itself is correct as well.
The end result is that our documentation always matches the input/output from our endpoints and that all the examples in the documentation are treated at valid input/output.
I would really recommend this workflow for documenting API endpoints. -
TobiSGD2815y"code does does replace a good documentation"
I do not agree with that completely. Code does only replace the documentation for how you do something, but it does not replace that explains why you do it in a certain way. -
rshetty855yAgree with it, I meant Code does not replace the documentation, could not edit the original rant
-
Marl3x26785yI love to document my stuff, it infuriates me that people write code, are even passionate about it, but can't be bothered to document it, so others can use it.
That's just selfish.
Related Rants
Treat documentation as first class folks. DOCUMENTATION is important. And yes, code does does replace a good documentation. Code and documentation are not mutually exclusive.
rant
documentation
coding