Build elegant server interface & test document with Swagger + Yapi

preface

Anyone who has done any development has suffered from interface documentation to some extent. The front end often complains that the back end provides interface documentation that is inconsistent with reality. The back end feels that writing and maintaining interface documentation takes too much effort to update. In fact, whether the front end calls the back end, or the back end calls the back end, all expect a good interface documentation. But the interface documentation is just like comments for programmers, who often complain that other people’s code is not commented, but when they write their own code, the worst thing is to write comments. So it’s not enough to just regulate people by force; over time, as versions iterate, it’s easy for interface documentation to fall out of sync with the code.

Write wiki documents on the GitLab private library

Early backend interface documentation for our team was written on a wiki in our internal GitLab private library project, something like:

However, this can lead to the same problem as above, which is that as the interface iterates, the maintenance of subsequent documents gradually falls behind. And then it’s very formal.

Use Swagger to generate interface documentation and test

Swagger is then used to generate interface documentation for the project, and interface request testing is also supported.

Swagger is a canonical and complete framework for generating, describing, invoking, and visualizing RESTful Web services.

The overall goal is to have clients and file systems update at the same rate as servers. File methods, parameters, and models are tightly integrated into server-side code, allowing the API to always be synchronized. Swagger makes deployment management and using powerful apis easier than ever.

1. Build Swagger UI

Because Swagger UI is a static site, you only need a local Web Server. Git Clone swagger Github git clone

Although the project file is quite large, all we really need is the static resource file in the dist directory

So we put the files under Dist in the Swagger directory under the Web server, so that we can access them directly

There’s a pre-filled JSON here by default

http://petstore.swagger.io/v2/swagger.json
Copy the code

You can later modify this configuration in index.html to a JSON file generated by our own project

The JSON file is the Swagger UI document configuration file. It is from this JSON document that he generates the interface and test documents. The JSON format looks like this:

After the substitution is complete, we can see the documentation for our project:

Interface testing cannot be done at this time, because this is built locally, so there will be cross-domain problems with projects directly requested on the line. However, if deployed to the same domain online, or if the interface has CORS set, this is ok.

2. View the interface and test

Once your JSON file has documented the interface, you can view the documentation directly on Swagger and also test the interface.

Click the Try it out button to test the interface

Very convenient.

3. Generate the JSON file

We can see that all of swagger UI’s resources are static, all generated by loading the JSON file we set to generate the interface document. So how is this JSON file generated? In the case of our PHP project, finding the DOC interface, you can see that the code is simple

/** * Generate API doc *@return Swagger\Annotations\Swagger
 */
public function doc()
{
    $swaggerStr = Swagger\scan(base_path('app'));
    // header('Content-Type: application/json');
    $data = json_decode($swaggerStr.true);
    $data['host'] = config('app.doc_host');
    // return $swaggerStr;
    return $this->echoJson($data);
}
Copy the code

He’s just invoking a swagger third-party package

The json document is then generated based on the rule-compliant comments set for each interface (in accordance with swagger syntax), so a normal JSON document would look like this

Of course, if there is a syntax problem, it will report an error

4. The swagger syntax

To generate an interface document for an interface, you need to write a comment that complies with The Swagger syntax on the corresponding interface. Take the DES encryption interface in the screenshot above as an example, then its Swagger syntax comment is:

    / * * *@SWG\Definition(
     *         definition="DesText",
     *         required={"text"},
     *         @SWG\Property(* Property ="text", * type="string", * format="string", * description=" string to be encrypted and decrypted "*), *) */


    / * * * *@SWG\Post(* path="/utils/des/encrypt", * tags={" des "}, * summary=" DES encrypt/json/text encrypted to Q string (old Q string)", * description=" return 200 is successful ", *@SWGParameter(* name=" encrypted message string ", * in="body", * description="raw body for the string to be encrypted ", * required=true, *@SWG\Schema(ref="#/definitions/DesText"),
     *     ),
     *     consumes={"application/json"},
     * produces={
     *         "application/json"
     *     },
     * @SWG\Response(* Response =200, * description=" success ", *), *@SWG\Response(* Response ="500", * description=" encryption failed failed ", *@SWG\Schema(ref="#/definitions/Error")
     *     )
     * )
     * @param Request $request
     * @return mixed
     */
    public function encrypt(Request $request)
    {
        $key = $request->get('key');
        if ($key && $key! =' ' && $key! ='{key}') {
            $this->rebuildDes($key);
        }
        $input = file_get_contents('php://input');
        //$input = $request->input('text');
        return $this->des->encrypt($input);
    }
Copy the code

So you just need to fill in the corresponding Swagger annotation when writing or iterating the interface, and then you can generate the corresponding interface document. Sort of solved the pain points above.

For Swagger’s Annotation syntax, see Quick Annotation Overview

Use YApi to build a more elegant document interface

1. Swagger UI interface issues

Swagger UI can handle interface documentation and testing well, but when there are many interfaces in this project, it is a nightmare to find a certain interface, because it has no search function and no favorites function. Every time to find an interface, it depends on chrome’s CTRL + F global search. Every time you have to interface with several tools, you have to find blood vomiting

However, there are a lot of jokes about the interface of Swagger UI on the Internet, and there are some defects in the function (for example, during the test, you can’t customize the header, and you can’t write the automatic test script), so there are some excellent services that are compatible with Swagger. One of them is YApi, which not only enhances testing functionality, but also has a more elegant interface

2. YApi profile

YApi is an efficient, easy-to-use, powerful API management platform, which aims to provide more elegant interface management services for developers, products and testers. YApi has accumulated 18K+Star on Github and has excellent interactive experience. YApi not only provides common interface management functions, but also provides permissions management, Mock data, Swagger data import and other functions. In short, it is very powerful!

3. The installation

3.1 Environment Preparation

To install YApi, nodeJS and mongoDB need to be installed first, so install it first. Nodejs and mongoDB were already installed in my local environment. I’m not going to do much here

By the way, my local environment is Windows 7

3.2 installation yapi – cli

Yapi-cli is an installation tool provided by YAPI. You can deploy yAPI services on a visual interface.

F: \ server - readme > NPM install - g yapi - cli - the NPM registry https://registry.npm.taobao.org WARN deprecated [email protected]: Fixed a critical issue with BSON serialization documented in CVE-2019-2391, see https://bit.ly/2KcpXdo for more details C:\Program Files\nodejs\yapi-cli -> C:\Program Files\nodejs\node_modules\yapi-cli\bin\yapi-cli C:\Program Files\nodejs\yapi -> C:\Program Files\nodejs\node_modules\yapi-cli\bin\yapi-cli + [email protected] added 257 packages in 48.635sCopy the code

After the installation, run the yapi server command to start the yAPI visual deployment page.

F:\server-readme>yapi server in the browser open http://0.0.0.0:9090 access. For a non-local server, replace 0.0.0.0 with the specified domain name or IP addressCopy the code

So go to http://127.0.0.1:9090/ next to install yAPI

Modify the path and other parameters

Click Start Deployment, and the deployment log appears

Error: the local version of Mongo is too low. At least version 2.6 is required.

Error:  error: MongoNetworkError: Server at 127.0.0.1:27017 reports maximum wire version 0, but this version of the Node.js Driver requires at least 2 (MongoDB 2.6), mongodb Authentication failed
Copy the code

Later, I checked the mongo installed locally and found it was 2.4.4, the version was too low

So we need to install a higher version of mongoDB, if it is above 2.6, because there is already an older version of mongoDB, the default port 27017 is already used, so the new higher version of mongoDB will run on port 27018

3.3 Install mongoDB of a later version and use port 27018

Through www.mongodb.com/try/downloa. We downloaded version 4.0.21. After the installation, the mongod. CFG startup port in the bin directory of the installation directory is changed to 27018

After the change, the service should be started (the above mongoDB service is an old version).

At this point, the version is 4.0.21, which finally meets the requirements.

So go ahead and deploy, but change the database port on the deployment screen to 27018, and you’re done

3.4 Starting the Service

Now that the deployment is successful, it’s time to start the YApi service

F:\my-yapi>node vendors/server/app.js log: -------------------------------------swaggerSyncUtils constructor----------------------------------------------- log: The mongodb service has been started. Please open the following link: http://127.0.0.1:3008/ log: mongodb Load Success...Copy the code

This way the service starts, and unlike Swagger UI, YApi has user rights management. So log in.

Log in using the administrator account [email protected]:ymfe.org above

Use 4.

4.1 Creating a Project

Next we need to import data from Swagger. First we need to create a group

Then under that group, click Add Item

After successful creation, you can see that the interfaces inside are empty

4.2 Importing the Swagger JSON File of the Project

Next we need to import the JSON file of the Interface document for the Swagger project and click Data Management

Click upload and a prompt will pop up

Click ok. When the export is successful, the API interface in Swagger of one of our projects has been successfully imported into YApi. Click the interface label to view all the imported interfaces. You can see that the interface list has our interface

And the whole pattern is very clear. Click interface details to view detailed information, including remarks

4.3 Setting the Url for an Interface Request

Next try the interface run function, we will find that the default interface request address does not meet our requirements, need to be set in the environment configuration;

We found that the requested address was not what we wanted, so this has to be changed, so click Environment Configuration

Click Environment Configuration

That’s it.

4.4 Installing the Cross-domain Plug-in for Chrome

Because it is a local environment, and the request is a business service interface, so there will be cross-domain request (later let the operation and maintenance personnel also put the YApi line, there will be no cross-domain request), Chrome browser needs to install the cross-domain request plug-in, download the address, here is the installation document

So we need to install this plugin, otherwise the send button won’t click.

Click to download the zip package, unzip it, and then go to Chrome’s extensions and click load the unzipped extension

Then refresh the YApi page and see that the send button is ready to click

Then set the parameters, hit Send, and you’re done

4.5 set the header

And even better than Swagger UI, it allows you to configure the Header. Because some of our interfaces have security checks, and the security check token is actually put into the header for request. Instead of putting it in the body argument.

So we can set our custom headers in the Settings environment. (Think of Postman)

Click Save, and when you request it, you’ll see the request header with the custom header

At this point you can see that the custom header will be carried over. Then test the interface with the Token header, especially useful.

Automatically sync from Swagger

We can set -> Swagger Automatic synchronization to enable automatic synchronization. There are three data synchronization modes to choose from. We choose full overwrite and give the interface definition to the back end

Use the default value, perform synchronization every two minutes, you can see the log output

Log: timer trigger, syncJsonUrl:https://test-admin.xxx.com/v2/doc, merge mode :merge log: Timer trigger, syncJsonUrl:https://test-admin.xxx.com/v2/doc, merge mode: Merge log: Timer trigger, syncJsonUrl:https://test-admin.xxx.com/v2/doc, merge mode: Merge log: The timer is triggered. SyncJsonUrl :https://test-admin.xxx.com/v2/doc. Merge mode: MergeCopy the code

6. A mock function

Since our interface definitions are all handled by the back end, we generally don’t use mock functionality. You can use the mock function to give the front end a mock interface and return value.

For example, I created a new interface from the public category called Get Custom User information

Then edit and set the mock return value

Finally, just request the mock address (there is a corresponding mock address under the display details of each interface) and you’re done

This is very convenient.

7. Permission management

YApi has permission management. What if a new member joins and needs to see the API documentation? It can be divided into three steps

1. First you can register a member account through the registration interface
2. Then log in with the administrator account and add the user to the corresponding group by choosing Member list > Add Member
3. Finally, log in with a member account to access the corresponding API document.

For more information about YApi permission management, see Permission rights

conclusion

Through the combination of Swagger + YApi, we can well achieve the compilation and testing of interface documents of the project. In particular, the addition of the latter, YApi, addresses several pain points of previously using only Swagger UI:

1. Swagger’s interface is too difficult to search for interfaces. With YApi, you can quickly locate interfaces through tag and search, or create a category for favorites
2. [Root@swagger] [root@swagger] [root@swagger] [root@swagger
3. YApi can set mock return values, allowing the front end to debug the interface without a background implementation
4. YApi can store interface documents for multiple projects, whereas Swagger has to switch json links to view documents for other projects
5. YApi provides permission management functions to ensure the security of API documents

---

Reference Documents:

• When Swagger meets YApi, instantly high up!
• Swagger interface ugly, weak function how to break? Use Postman to enhance it!
• YApi documents
• Swagger Quick Annotation Overview

---

See my personal site: kebingzao.com/ for more good articles