Nanny level document – interface platform Yapi and interface document generation plug-in deployment and use

preface

First, to describe the background: since the business of the new company belongs to self-developed product development, it is found that the interface documents of each product business line are maintained temporarily by integrating Swagger, knife4J (Swagger’s enhanced solution) to be exact. However, for product development, there will be some problems, such as the project code is highly intrusive, version compatibility problems, the document is not fully standardized, the team can not cooperate online and so on. Swagger is more suitable for some industry project software development with low requirements on interface specification and maintenance. Compared with development, interface document generation and debugging are more convenient and quick.

Therefore, based on my previous experience and other interface document platforms, the research is as follows:

The framework	Swagger	Yapi	Showdoc	ApiPost
Code intrusion	strong	There is no	There is no	There is no
Privatization deployment	support	support	support	Does not support
Whether open source	is	is	is	no
Learning costs	higher	easy	easy	higher
Automatic document generation	support	Plug-in support	Client required	support
The Mock data	support	support	Not supported (client required)	support
Automated testing	Does not support	support	Client required	support
Data import	Does not support	Support the postman/swagger/har/json	Does not support	Support the postman
note

Of course, there are many other platforms that can be used for interface document maintenance, such as Postman, RAP, EasyAPI and other platforms, as well as documen-based platforms such as lark, graphite document and Wiki, which have their own advantages and applicable business scenarios.

Finally, we decided to use the open source platform Yapi that supports private deployment and swagger synchronous import to save and maintain interface documents in each project. Inevitable, of course, as a free open source products, it will also have some defects, such as the open source low maintenance degree (resulting in a community activity is relatively reduced a lot), the platform directory hierarchy does not support more than secondary (need to secondary development, although some fork version support, but low version), some versions of bug (issue), etc.

However, all these have little impact. The most important thing is to consider that the current actual needs of the company’s business and technical team and their subsequent expansion can be basically well met.

Yapi deployment – docker

First of all, the Yapi project is open source on GitHub by Qunar. There is a detailed introduction in the official document, as well as the experience address of the platform, so I won’t go into too much here.

Since docker has been used to build the environment in the company’s project, this paper mainly introduces how to make deployment based on Docker image (non-Docker environment recommended official YAPI-CLI tool deployment document, easy to use, and seamless support version upgrade; Rather than some blog posts, which may be reversely misleading due to uneven description and level).

In fact, the way of docker deployment is basically similar to non-Docker, but there is a more image making in the process. Some blog articles on the market have also been introduced, including some images that have been made and pushed, but the latest version 1.10 of Yapi image making deployment has not been found yet. It looks pretty much the same, but in practice there are a few bugs; At the same time, their own image is more secure.

First, we learned about the environmental requirements of Yapi:

• Nodejs (+ 7.6)
• Directing (+ 2.6)

Directing a deployment

Since the interface data is stored using NoSQL database mongodb, we need to install and deploy mongodb first.

1. Download the official image. Select 4.2.6

docker pull mongodb:4.2.6
Copy the code

Run the docker images command to see that the image has been downloaded

2. Start the container

 docker run  \
--name mongo \
-p 27017:27017  \
-v /data/yapi/mongodb/data/configdb:/data/configdb/ \
-v /data/yapi/mongodb/data/db/:/data/db/ \
-d mongo:4.2.6 --auth
Copy the code

• -p 27017:27017: indicates the access port of the mapping container.
• -v: Mount the data in the MongoDB container to an external directory. In this way, the original data can be protected if the container cannot be restored and started due to unexpected accidents.
• –auth: requires a password to access MongoDB.

Using the docker ps command, you can see that the container has started normally

3. Set the user password

Use the following command to enter the container, go to the MongoDB command line, and switch to the admin database

docker exec -it mongo mongo admin
Copy the code

Set up a user and password, and verify that they are correct

db.createUser({ user:'admin',pwd:'123456',roles:[ { role:'userAdminAnyDatabase', db: 'admin'}"readWriteAnyDatabase"]});

#validation
db.auth('admin', '123456')
Copy the code

At this point, MongoDB deployment is complete, follow up to pay attention to the MongoDB data file backup on a regular basis (many related articles, here will not be described).

Yapi deployment

To deploy Yapi, we need to make our own Docker image. There are two ways

• The source code to compile
• Official YAPI – CLI tool

The source code compilation is slightly more complicated, depending on the environment of different versions may produce some pits, and the version upgrade is relatively troublesome; The second method, yapi-CLI, is recommended.

1. Write Dockerfile

vi Dockerfile

#content
FROM node:11
RUN npm install -g yapi-cli --registry https://registry.npm.taobao.org

EXPOSE 3000 3000
Copy the code

2. Write the docker – compose

Docker-compose is used for image creation and deployment.

vi docker-compose.yml

#contentVersion: '3' services: yapi: build: context:./ dockerfile:./ dockerfile image: yapi:1.10.2 container_name: Yapi # first start using the command: "yapi server" # after using the following command # command: "node/my - yapi/vendors/server/app. Js" ports: Volumes: -./my-yapi:/my-yapiCopy the code

• Dockerfile: Run the dockerfile in the current directory to create an image.
• Image: indicates the name and tag of the image.
• Volumes: Mount yapi files, including configuration files, to an external directory.

Docker-compose: docker-compose: docker-compose: docker-compose: docker-compose: docker-compose: docker-compose: docker-compose: docker-compose

3. Create an image and install it

Once you have written the required files, execute the following command,

docker-compose up
Copy the code

The first step is to download node:11, the basic image for yAPI

After downloading, you can see the following console, indicating that yAPI-CLI startup is complete

Because we will be mapped to port 9091, 9090 just now so here visit http://192.168.24.240:9091 (192.168.24.240 for hosting IP), can see the web page display as follows,

Next, we will set up the installation directly and click “Deploy” to install the version of YAPI we want. After that, we will see the page and the console will keep scrolling the installation log until we see the following message indicating that YAPI has been downloaded and installed.

4. Start

-./my-yapi:/my-yapi :/my-yapi :/my-yapi :/my-yapi:

Json file is the basic configuration file of Yapi. You can set administrator account, MongoDB connection configuration, email notification, etc. For details, refer to the official documentation.

Modify docker-comemage. yml as follows:

Version: '3' services: yapi: build: context:./ dockerfile:./ dockerfile image: yapi:1.10.2 container_name: Yapi # # the first time you start using the command: "yapi server" # after using the following commands command: "node/my - yapi/vendors/server/app. Js" ports: Volumes: -./my-yapi:/my-yapiCopy the code

After the modification is complete, save and exit, and use the following command to start directly.

docker-compose up -d
Copy the code

• -d: Background startup

After starting up, using Docker PS, you can see that our Yapi container has started up,

Using docker images, you can also see the image file we made for 1.10.2.

5. Access

After the startup is complete, our browser is directly accessedhttp://192.168.24.240:3000And you can see,

Next, we will log in and use the administrator account and default password ymfe.org.

Some suggestions for use:

1. Add different project groups by the administrator or each project leader and add group members;
2. Under the project group, new projects are categorized by the iteration version of the project, and the version number is carried by the project name as a distinction.
3. Test sets can be used to develop use-case self-testing including process automation tests that may not meet the actual needs of testers.

Interface document generation plug-in

Although Yapi has taken over the interface documentation platform to meet the documentation needs of development teams, we know that most developers using Swagger are probably most concerned with the automatic generation of interface documentation through annotations, which eliminates the need for manual writing and increases productivity.

Because Yapi platform opens relevant API, it also supports external generation. At present, the company’s developers basically use IDEA as a development tool, so only some plug-ins supporting IDEA have been investigated.

After comprehensive use and comparison of several IDEA plug-ins, such as YapiUpload, EasyYapi, Yapi X, etc., it is found that the configuration support of EasyApi plug-in is relatively friendly, the code is basically non-invasive during document generation, and the customization function is powerful, etc. At the same time, it meets the high standardization demand of project interface document generation. Although the threshold for using custom functions is high, there is basically no need to change after the project is configured. For details about configuring custom rules and using custom functions, see the documents on the official website.

Use steps:

1. Open File/Settings/Plugins to search EasyYapi, select Install and restart IDEA.

   

2. Go to File/Other Settings/EasyApi and configure Server and tokens under Yapi:

Yapi address of the server that is deployed, such as: http://192.168.20.24:3000 tokens that Yapi projects for the request of openapi private token, access to the project – > Settings – > token configuration – > tool logos

3. Three ways to generate interface documentation and upload it to Yapi (first use may require token input in a popup) :
   • Open the file containing THE API in the project or select the file or folder in the left project file area of IDEA. Right-click the file or folder and choose ExportYapi to export all the APIS in the file or folder.
   • Open the file that contains the API in your project or click the file or folder in the project file area on the left of your IDEA. Use the shortcut keys Alt Shift E(Windows)/ CTRL E(MAC) to select the API to export, select the export channel Yapi, and click the configure button
   • Click Code > YapiDashBoard at the top of the mouse, then drag the API on the left to the yAPI directory on the right to complete the API export to yAPI

Note that to generate a relatively formal interface document, you need to write a fairly complete code comment, as follows (simple annotated Demo) :

/** * Category name * Category Remarks/Description */
@RestController
@RequestMapping(value = "/demo")
public class DemoController {

    /** * API name * API description *@paramParam1 Specifies the name or description of parameter 1 *@paramParam2 Specifies the name or description of parameter 2 *@return* /
    @GetMapping(value = "/test")
    public Result<Demo> methodName1(@RequestParam String param1,
                                    @RequestParam(required = false, defaultValue = "1") Integer param2){... }}public class Demo {
    /** ** **
    private Long field1;
    /** ** javax.validation is valid@NotBlank/@NotNullIndicates that the field must */
    privateString field2; . }Copy the code

After uploading through the plug-in, you can see the generated interface documentation in the platform directory.

Usage suggestions:

1. Interface documents automatically generated by plug-ins need to check whether the generated documents are correct and standard, and manually edit and correct the incorrect or non-standard documents.

2. For some global configurations, you can create.yapi.config in the project or module directory (see official documentation for configuration).

   Arguments ignore specific classes
   param.ignore=@java.lang.String
   Parameter description suffix
   param.doc=Type groovy: ", "" + tool. Uncapitalize (it. The type (). The name (). The replace (" Java. Lang.", ""). The replace (" Long", "String")) + ">"
   # Long转String
   json.rule.convert[java.lang.Long]=java.lang.String
   # unified return body
   method.return[#return]=groovy: "com.xxx.xxx.Result<" + it.returnType() +">"
   Copy the code

Reference documents: github.com/Ryan-Miao/d…

---

The body does not move, the heart is far.

To do one thing extremely well is talent!