Hacker Newsnew | past | comments | ask | show | jobs | submitlogin
Ask HN: What do you use for internal API docs?
5 points by arihant on April 10, 2015 | hide | past | favorite | 5 comments
Our codebase is sizing up considerably. Moreover, we are moving to different platforms and it's becoming hard to keep track of APIs (private and public) for even the guys who wrote them.

Is there a better way to manage this? Some kind of tool that takes stuff like javadoc and turns it into pretty, searchable interfaces? Something that extracts data from Git repo? An IDE plugin? Anything but the abomination that we're dealing with right now.

I'm sure this is a common pain. How do you manage this?



Do the inline documentation with the apiDoc format[1]. Readme.io has also created and documented a superset of apiDoc that you might want to look into. Obviously their tool supports it, but it seems easy to roll your own frontend for the API data once you extract it from your code.

1. http://apidocjs.com/


Thanks for the rec! I'm obviously super biased (ReadMe founder, here), but ReadMe was built for this kind of scenario, spot on. apiDoc is good for keeping the endpoint docs up to date, and you can keep it internal with a password or admin-only access. Search should be improving later this month.


ReadMe is the one that looks very promising. But somewhere on HN, someone from your team commented that internal use is frowned upon and the system gets more and more naggy if used internal only. Is that still true? If yes, does that stop after we start paying?


Lot's of people seem to like https://github.com/tripit/slate


There's also Swagger: http://swagger.io/




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: