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+R
Open the Run window with the shortcut key, and entercmd
Press enter to open Windows Shell.
Then, enternode
Command 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, enternpm
Command. 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 -g
Install 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\apidoc
Path. In this directory, createsrc
Directory of the Project. Place the apidoc. json and Demo1.java files under the src directory.
Then, enterapidoc -i src/ -o apidoc/
Command, ifDone
The 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.html
You 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:
@api
In the following format:
@api {method} path [title]
Note: [xxx] indicates an optional parameter.
The following table describes@api
Parameter description in.
Parameters |
Description |
Method |
The HTTP Method Name of the request, includingDELETE ,GET,POST ,PUT For 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
@apiDefine
Defines a variable. This variable can refer to any value (string or parameter block). This parameter is written in an independent code block. Available@apiUse
To use the Defined variables.
@apiDefine
In the following format:
@apiDefine name [title] [description]
The following table describes@apiDefine
Parameter 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@apiParam
Parameter description in.
Parameters |
Description |
(Group) |
The group where the parameter is located. You can use@apiDefine Defined 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.
@apiSuccess
In 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.
@apiError
In the following format:
@apiError [(group)] [{type}] field [description]
The parameter meanings are exactly the same as those of apiSuccess.
@ ApiParamExample
Indicates a request example.
@apiParamExample
In 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.