Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

how to generate api documentation [closed]

I need to write some api documentation for a REST API that I've created. Are there tools that will stub out a nice html output similar in style to the underscore api documentation? Or perhaps something that will output something as a twitter bootstrap styled html?

I see that docco does annoated code, but I'm actually just looking to document the API only. Ideally I'd like to point a tool at the controller file and have it generate documentation about the methods and routes but not show any source code unless I specifically call out examples.

like image 438
MonkeyBonkey Avatar asked Aug 15 '12 12:08

MonkeyBonkey


People also ask

Should API documentation be public?

If only developers within your own company use your API, its documentation is likely also internal. However, it should be easily discoverable. You shouldn't have to know who to ask. For APIs used outside your organization, make your documentation public.

How do I create API documentation template?

Introduction: Explain in each section what you will be going over. Tutorials: Provide a detailed step-by-step guide of that part of the API. Examples: It's always a good idea to provide examples. Code Snippets: Whenever necessary share the code snippets with your reader to help them connect the dots.


2 Answers

apiDoc creates a documentation from API annotations in your source code.

Integrated is an API history, with that various API version levels can be compared. So it can be retraced what changed in the API since the last version.

Demo: http://apidocjs.com/example

Github: https://github.com/apidoc/apidoc

like image 139
Diogo Cardoso Avatar answered Sep 28 '22 00:09

Diogo Cardoso


Check out I/O Docs on Github - http://github.com/mashery/iodocs . It's hacked in Node.js, and has a lot of community contribution/involvement. To see it working in the wild:

  • http://iodocs.docusign.com
  • http://console.datasift.com/datasift

Uber simple configuration schema (JSON), and hell, if you don't want to describe it all by hand in JSON, use I/O Doctor, a web-based tool for importing/building JSON configs with a UI:

  • http://iodoctor.net/

Also available on Github at https://github.com/brandonmwest/iodoctor

Let me know if I can help you get started. There are plenty of example configs in the I/O Docs repo. Take care.

like image 21
mansilladev Avatar answered Sep 27 '22 22:09

mansilladev