Ask HN: What do you use for internal API docs?

Posted by arihant on Friday April 10, 2015 @06:14PM
from the ask-hn dept.

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?

( 5 comments | 5 points | on HN )

Re:Ask HN: What do you use for internal API docs? by smt88 on Friday April 10, 2015 @06:27PM (#9357443)

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/

[ Parent | on HN ]

Re:Ask HN: What do you use for internal API docs? by gdillon on Saturday April 11, 2015 @06:22PM (#9361071)

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.

[ Parent | on HN ]

Re:Ask HN: What do you use for internal API docs? by arihant on Sunday April 12, 2015 @01:16PM (#9364021)

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?

[ Parent | on HN ]

Re:Ask HN: What do you use for internal API docs? by anonfunction on Friday April 10, 2015 @06:49PM (#9357540)

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

[ Parent | on HN ]

Re:Ask HN: What do you use for internal API docs? by cjbprime on Friday April 10, 2015 @06:29PM (#9357451)

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

[ Parent | on HN ]