4 ms·

Any recommendations on good doc frameworks/products? We're about to begin redoing our documentation at print.io. Currently we're using swagger (https://api.pri

Any recommendations on good doc frameworks/products? We're about to begin redoing our documentation at print.io. Currently we're using swagger (https://api.print.io/docs/ https://api.print.io/docs/) and "self-documentation" (http://print.io/api http://print.io/api) but i still find that we have a lot of questions.

raus22 12y ago
e.g. http://docs.themoviedb.apiary.io/#reference/collections/collectionid/get http://docs.themoviedb.apiary.io/#reference/collections/coll... where TMDB use apiary, and with quick examples with the different inputs and outputs. So you can test it out right away WITHOUT needing to find ID's to use for test. This provides real response values, as to know what you get when you send some value.
pksunkara 12y ago
You can try using API Blueprint (https://apiblueprint.org https://apiblueprint.org) which is based on Markdown can host your API docs at http://apiary.io http://apiary.io Disclaimer: I work at Apiary
- Erwin 12y ago
  For our corporate API, we the Apiary markdown with aglio to convert into nice documentation. I've tried RAML (I didn't like the giant YAML file) and apidoc (I didn't like to put 100 lines of user documentation next to 20 lines of implementation). I use protagonist to convert the md file to JSON which my Python code can load and compare with the decorated API endpoints -- I can then verify they and all their parameters are properly documented. I don't use the fancy Apiary features yet.
buro9 12y ago
I find all of the auto-generated systems produce barely sufficient documentation. Real documentation is written by a person who understands how to use the API. Unfortunately, such documentation then suffers bit-rot if it's not updated whenever the API is updated. What I would like to see is some way to describe an API which can be merged with the hand-written narrative and instructions, and can be refreshed whenever the implementation changes.
biscotti 12y ago
We're using swagger to great effect, the ability to add markdown against the endpoints allows us to describe them with both relevant documentation and examples. http://oi60.tinypic.com/33llco5.jpg http://oi60.tinypic.com/33llco5.jpg
timjones 12y ago
Definitely check out http://readme.io http://readme.io. Their docs look beautiful and set-up is a breeze.
- gdillon 12y ago
  Thanks for the tip, Tim! Happy to answer any questions folks have about my product. Also, plugging: Swagger support in just a few weeks. And we can currently auto generate endpoint reference docs from your source code using a commenting standard similar to javadoc. We get all sorts of excited by good API documentation. Weird, right? Apparently not, based on this thread. :D
goatandsheep 12y ago
More of a product, but codecademy (http://www.codecademy.com/learn http://www.codecademy.com/learn) has a number of APIs it covers how to use.

raus22 12y ago

e.g. http://docs.themoviedb.apiary.io/#reference/collections/collectionid/get http://docs.themoviedb.apiary.io/#reference/collections/coll... where TMDB use apiary, and with quick examples with the different inputs and outputs. So you can test it out right away WITHOUT needing to find ID's to use for test. This provides real response values, as to know what you get when you send some value.

pksunkara 12y ago

You can try using API Blueprint (https://apiblueprint.org https://apiblueprint.org) which is based on Markdown can host your API docs at http://apiary.io http://apiary.io Disclaimer: I work at Apiary

Erwin 12y ago
For our corporate API, we the Apiary markdown with aglio to convert into nice documentation. I've tried RAML (I didn't like the giant YAML file) and apidoc (I didn't like to put 100 lines of user documentation next to 20 lines of implementation). I use protagonist to convert the md file to JSON which my Python code can load and compare with the decorated API endpoints -- I can then verify they and all their parameters are properly documented. I don't use the fancy Apiary features yet.

buro9 12y ago

I find all of the auto-generated systems produce barely sufficient documentation. Real documentation is written by a person who understands how to use the API. Unfortunately, such documentation then suffers bit-rot if it's not updated whenever the API is updated. What I would like to see is some way to describe an API which can be merged with the hand-written narrative and instructions, and can be refreshed whenever the implementation changes.

biscotti 12y ago

We're using swagger to great effect, the ability to add markdown against the endpoints allows us to describe them with both relevant documentation and examples. http://oi60.tinypic.com/33llco5.jpg http://oi60.tinypic.com/33llco5.jpg

timjones 12y ago

Definitely check out http://readme.io http://readme.io. Their docs look beautiful and set-up is a breeze.

gdillon 12y ago
Thanks for the tip, Tim! Happy to answer any questions folks have about my product. Also, plugging: Swagger support in just a few weeks. And we can currently auto generate endpoint reference docs from your source code using a commenting standard similar to javadoc. We get all sorts of excited by good API documentation. Weird, right? Apparently not, based on this thread. :D

goatandsheep 12y ago

More of a product, but codecademy (http://www.codecademy.com/learn http://www.codecademy.com/learn) has a number of APIs it covers how to use.