Use apidocJs to quickly generate online document examples and apidocjs instances

Use apidocJs to quickly generate online document examples and apidocjs instances

Apidoc is a lightweight online REST interface document generation system that supports multiple mainstream languages, including Java, C, C #, PHP, and Javascript. Users only need to write relevant comments as required to generate online interface documents with good readability and beautiful UI.

This article includes the following content:

1. Introduce the basic concepts of apidoc

2. installation, use, and simple configuration

3. Meanings and usage of some special parameters

4. Introduce some user experience

Preface

What can apidoc do?

Apidoc is a lightweight online REST interface document generation system that can generate static Web Pages Based on the Code annotations of specific rules. First, let's take a look at the document interface and style it generates.

Supported

Apidoc supports multiple mainstream encoding languages, including Java, C, C #, PHP, and Javascript. In general, the language has multiple annotation methods, such as multi-line and Javadoc-style annotations in Java. Apidoc does not support all annotations. For example, Java only supports Javadoc-style annotations. The first thing to note is that apidoc does not have semantic recognition capabilities and does not find any bugs in the Code. It only uses the file suffix to determine the language type. Below are some annotations for different languages:

* Java, Javascript, PHP *

/** * @api {get} /user/:id Request User information * @apiName GetUser * @apiGroup User * * @apiParam {Number} id Users unique ID. * * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. */

* Python *

"""@api {get} /user/:id Request User information@apiName GetUser@apiGroup User@apiParam {Number} id Users unique ID.@apiSuccess {String} firstname Firstname of the User.@apiSuccess {String} lastname Lastname of the User."""

Install

Apidoc is based on the nodeJs platform. You must install nodeJs before installing apidoc. Regarding the installation of nodeJs, I will try again. But for the sake of article integrity, I should first introduce the installation of nodeJs on the Windows platform.

NodeJs Installation

First, download the latest installation package from the node. js website. Download the installation package of your system. For example, if my operating system is a 64-bit Windows operating system, download the node installation package.

After the download is complete, follow the general software installation steps. Since my computer has been installed, I will not elaborate on it here.

It is reasonable to say that the node environment has been configured after the installation steps are completed. Now, verify whether the node has been correctly installed and configured.

First, open the Window Shell Window. Usewin+ROpen the Run window with the shortcut key, and entercmdPress enter to open Windows Shell.

Then, enternodeCommand to enter the node console.

Finally, run a Hello World Program. Enterconsole.info("hello world");If the result is as shown in, the node installation and configuration are successful.

In addition to node, npm (node package manager and node Installation package manager) is also very important. You can use it to conveniently download and install the node application. In Windows Shell, enternpmCommand. If the information shown in is displayed, npm is correctly installed.

Install apidoc

Apidoc can be quickly installed using npm.

1. Go to Windows Shell and enternpm install apidoc -gInstall apidoc, for example.

After a certain period of time (based on your own network speed) is downloaded and installed, if the information shown appears, it indicates that apidoc is successfully installed.

2. Enter the apidoc-v command in Windows Shell. If the interface shown in appears, the apidoc is successfully installed.

Preliminary use

The following describes how to use apidoc to generate an online interface document through some simple demos.

Command Line

Before getting started, let's first introduce the important commands and parameters in apidoc. The Command Format of apidoc is as follows:

Apidoc Parameters

Some important parameters are shown in the following table:

Parameters	Description
-F	Select the file to be parsed. Regular Expressions are supported. The-f parameter can be used multiple times. Multiple Expressions can correspond to different-f parameters. For example:apidoc -f ".*\.js$" -f ".*\\.ts$"
-I	Select the source code location. For example:apidoc -i myapp/
-O	Select the location of the generated target file. For example:apidoc -o apidoc/
-T	Select a template for the generated file to create and use a custom template. (Note: I have not used this parameter so far)
-H	Like most commands, this parameter can print help documents.

Apidoc-I src/-o apidoc/# You can search for files in the src directory to quickly generate document files and put these files under the apidoc directory.

Apidoc-h # Show Help Information

Use apidoc

Shows the results of a typical file directory.

Where:

Apidoc. json: the project-level configuration file of apidoc, which must be located at the top of the entire project directory.

Demo1.java: demo source file used for demonstration. It can be located in the top-level directory of the entire project directory and Its subdirectories. Apidoc searches the entire project directory and selects all possible source files.

The Code contained in apidoc. json and Demo1.java is as follows:

{"Name": "demo", "version": "1.0.0", "description": "This is a simple apidoc demo", "title": "demo ", "url": "https://api.github.com/v1 "}

/** * @api {get} /user/:id Request User information * @apiName GetUser * @apiGroup User * * @apiParam {Number} id Users unique ID. * * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. */

The following demo describes how to generate a document file.

First, go to the upper directory of the apidoc project directory in Windows Shell. For example, the project of the author's apidoc is located inE:\workspaces\sublime\apidocPath. In this directory, createsrcDirectory of the Project. Place the apidoc. json and Demo1.java files under the src directory.

Then, enterapidoc -i src/ -o apidoc/Command, ifDoneThe result indicates that the document has been generated and is located in the apidoc directory of the same level (corresponding to-o apidoc.

Finally, open the apidoc directory and you can see the static Web file as shown in. Double-clickindex.htmlYou can open the website that generates online interface documentation in the browser.

In this way, we have successfully generated an online interface document. Next we can deploy it to any Web Container (Apache, Tomcat, and So on) to publish the interface document externally. So easy!

Configuration

The apidoc. json file is a project-level configuration file. Next, we will briefly introduce the commonly used configuration items.

Configuration name	Description
Name	Project name. If this field does not exist, apidoc will try to generate it through package. json (apidoc top-level configuration file ).
Version	The version number of the project document. If this field does not exist, apidoc will try to generate it through package. json (apidoc top-level configuration file ).
Description	Detailed description of the project. If this field does not exist, apidoc will try to generate it through package. json (apidoc top-level configuration file ).
Title	Document title, displayed at the top of the Document Interface
Url	The prefix of the entire api url.
SampleUrl	The url prefix of the api example. If this value is set, the request form is displayed on the interface, which can be used to test the interface.
Header
Title	Connection anchor name of the header
Filename	File used by the Document Header
Footer
Title	Link anchor name at the end of the document (footer)
Filename	File used at the end of the document
Order	List of interfaces. If not specified, apidoc determines the order.

A complete configuration file is as follows:

{"Name": "demo", "version": "1.0.0", "description": "This is a simple apidoc demo", "title": "demo ", "url": "https://api.github.com/v1", "sampleUrl": "https://api.github.com/v1/test", "header": {"title": "header", "filename": "header. md "}," footer ": {" title ":" footer "," filename ":" footer. md "}," order ": [" Error "," Define "," PostTitleAndError "," PostError "]}

For more configuration items, refer to the official apidoc documentation site.

Params

The core of apidoc is the writing of parameters (params). This section describes some important params in apidoc.

@ Api

@ Api defines a specific interface. If a comment block does not contain @ apiDefine and does not contain @ api parameters, apidoc directly ignores this comment block. This parameter indicates the following interface area on the interface:

@apiIn the following format:

@api {method} path [title]

Note: [xxx] indicates an optional parameter.

The following table describes@apiParameter description in.

Parameters	Description
Method	The HTTP Method Name of the request, includingDELETE,GET,POST,PUTFor more information, see http-learn-url.
Path	Requested url path (excluding the prefix)
Title	Interface Name, used for interface indexing. This configuration item is displayed in the navigation menu.

For more configuration items, refer to the official apidoc documentation site.

@ ApiDefine

@apiDefineDefines a variable. This variable can refer to any value (string or parameter block). This parameter is written in an independent code block. Available@apiUseTo use the Defined variables.

@apiDefineIn the following format:

@apiDefine name [title] [description]

The following table describes@apiDefineParameter description in.

Parameters	Description
Name	The value or block name can be viewed as the variable name.
Title	The title, which is generally used for the @ apiParam (name) parameter and displays the name of the group where the request parameter is located.
Description	Description of the variable.

The following code defines an error block and then references it in the interface definition. Multiple different interfaces can reference the same @ apiDefine block, which becomes the variable function of the language. This eliminates repeated code.

/** * @apiDefine MyError * @apiError UserNotFound The <code>id</code> of the User was not found. *//** * @api {get} /user/:id * @apiUse MyError */

@ Apide.pdf

It is used in the @ api code block to describe interface functions in detail.

@ Apide.pdf:

@apiDescription text

Text is the specific description. You can use the Markdown syntax directly, which greatly enriches the representation.

@ ApiGroup

Indicates the group to which the interface belongs. The most direct embodiment is to divide the interface in the peer group in the side navigation.

@ ApiGroup:

@apiGroup name

Name indicates the group name, which can be any string. It is worth noting that name does not support Chinese characters. Once you enter Chinese characters, apidoc ignores these Chinese characters. To display the Chinese interface group name on the interface, you only need to use @ apiDefine to define a Chinese string, and then replace the name with the variable name.

/*** @ ApiDefine group test * // *** @ api {get}/user/: id Request User information * @ apiName GetUser * @ apiGroup group */

@ ApiName

Indicates the interface name, which should be used in each @ api block. A Web anchor can be generated to quickly locate the interface location. You can see that the anchor (the string following the url #) is usually composed of groupName-apiName.

@ ApiName:

@apiName name

@ ApiUse

Reference a value or block defined by @ apiDefine, which is equivalent to directly replacing the value of the variable.

@ ApiUse:

@apiUse name 

Name is a defined name in @ apiDefine. If the input name does not exist, an exception similar to the following is thrown.

{ File: 'src\\Demo1.java', Block: 4, Element: '@apiUse', Groupname: 'test', Definition: '@apiUse group', Example: '@apiDefine MyValidGroup Some title\n@apiUse MyValidGroup' }

The following is an example:

/** * @apiDefine test * @apiParam {Number} id Users unique ID. *//** * @apiUse test * @apiParam {Number} name name. */

@ ApiParam

Indicates a request parameter.

@ ApiParam:

@apiParam [(group)] [{type}] [field=defaultValue] [description]

The following table describes@apiParamParameter description in.

Parameters	Description
(Group)	The group where the parameter is located. You can use@apiDefineDefined value
{Type}	Parameter type. For example, {Boolean}, {Number}, {String}, {Object}, {String []} (array of strings ),..
Field	Request Parameter Name.
[Field]	This parameter is optional and is optional.
= DefaultValue	The default value of this parameter.
Description	The description of this request parameter. The Markdown syntax is supported.

The following is a simple example:

/*** @ Api {get}/user/: id * @ apiParam {Number} id Users unique ID. * // *** @ api {post}/user/* @ apiParam {String} [firstname] user Name (optional ). * @ apiParam {String} lastname (required ). */

@ ApiSuccess

Indicates a returned field when the request is successful.

@apiSuccessIn the following format:

@apiSuccess [(group)] [{type}] field [description]

The parameter meaning of @ apiSuccess is the same as that of @ apiParam.

@ ApiError

Indicates a returned field when the request fails.

@apiErrorIn the following format:

@apiError [(group)] [{type}] field [description]

The parameter meanings are exactly the same as those of apiSuccess.

@ ApiParamExample

Indicates a request example.

@apiParamExampleIn the following format:

@apiParamExample [{type}] [title] example

Parameters	Description
{Type}	Format of request data
Title	Example title displayed on the page
Example	Entity example

The following is a simple example:

/** * @api {get} /user/:id * @apiParamExample {json} Request-Example: *  { *  "id": 4711 *  } */

@ ApiSuccessExample

A response example. The format and parameter description are exactly the same as @ apiParamExample.

@ ApiSampleRequest

Indicates an interface test block. You can generate a form based on the defined Request Parameters for interface test.

@ ApiSampleRequest:

@apiSampleRequest url

The url can be connected to sampleUrl in the configuration file (apidoc. json) and the path defined by @ api into a complete test url. For example:

/** * @api {get} /user/:id * @apiParam {Number} id Users unique ID. * @apiSampleRequest /test */

The generated interface is as follows:

Some practical experience

The following describes what is found during actual use.

Markdown syntax can be used in most cases.

Text that complies with the Markdown syntax can be used in almost all Description fields to make the document form more beautiful.

/*** @ Api {get}/user/: id * @ apiParam {String} rule **-rule 1: decimals cannot be used *-rule 2: cannot be added */

The front of the name and age fields is indented, and the fields are named name and age.

The above example of using apidocJs to quickly generate online documents is all the content shared by Alibaba Cloud. I hope you can give us a reference and support for the customer's house.