Drop word and use Apidoc to write documents

from:http://build.iteye.com/blog/2334273

In the process of developing interfaces, you need to publish the appropriate interface documentation. Start with Word to write the document, long time to find a few problems. 1) not easy to write. Each new excuse to copy the previous interface, and then to modify, some of the same parts can not be reused, the interface more documents will become very long, and often need to adjust the format. 2) not easy to publish. When a document is updated, it needs to be sent to a small partner. Even if the use of Git to manage, although pull more convenient, but due to file format problems, it is not convenient to compare two submissions of differences.

Because of these problems, you decide to find a more elegant and efficient way to write your document. After comparison, found the Apidoc, can better solve the above mentioned problems. Apidoc uses a code-like notation to write documents that support writing documents in multiple languages. The last generated document is published in the form of a Web page, convenient and easy to read. Here's a quick introduction to how to use Apidoc to write a document.

1. Install node

Because Apidoc relies on Node.js's package management tools NPM for installation, Node.js is installed before installing Apidoc (NPM installs node in passing). Specific installation tutorials can refer to here.

2. Install Apidoc

Once you have installed NPM, you can install the Apidoc. Enter the shell code at the command line NPM install Apidoc-g

is ready to be installed. Install complete Enter Shell code apidoc-h

A related hint Help message appears, indicating that the installation was successful.

3 Apidoc Common Notes Introduction

Apidoc is the use of various annotations to complete the writing of the document. Learning Apidoc is mainly about learning the usage of annotations. The commands for Apidoc and named rows are very similar, consisting of a single annotation keyword plus some options. Here is a brief introduction to Apidoc's main annotations. Apidoc code @api {method} path [title] This is a apidoc necessary annotation to illustrate the methods of the API, access paths, and functions. Apidoc Code @apiParam [(group)] [{type}] [Field=defaultvalue] [description] This annotation is used to describe the type, size, and effect of the API request parameters. Apidoc Code @apiSuccess [(group)] [{type}] field [description]

This annotation shows the type, size, and effect of the API return parameters.

Detailed usage of annotations can be accessed from the official website, with detailed usage and examples.

4. Writing Apidoc Documents

Once you've learned about the usage of annotations, you can use annotations to write your documents. For example, we can write a Getuser.java file.  The contents are as follows: Java code/** * @api {get}/user/:id Request User information * @apiGroup User * * @apiParam {number} ID   The Users unique ID.   * * @apiSuccess {String} firstname FirstName of the User.   * @apiSuccess {String} lastname LastName of the User. */

5 Generating Apidoc Documents

When writing is complete, run the shell code apidoc-i apidocin-o Apidocout

Apidocin represents the directory where Getuser.java files are stored, Apidocout represents the directories that you want Apidoc documents to generate. After running successfully, you can see a bunch of generated files in the output directory, where index.html is the document we need. You can see the effect when you open the browser. The effect is shown in the following illustration:

You can configure the Nginx, specify the path of the access map to the index.html, you can let the small partners who need documents to visit.