Kill Postman? The test interface directly generates API documentation, this tool is easy to use

Hello everyone, I am Xiaofu~

A few days ago, a small partner in the fan group asked if there is any useful API documentation tool recommendation. I accidentally found a tool. Here I will share it with you non-stop.

ShowDoc an online API documentation tool that is very suitable for the team. It also supports docker , but for the convenience of demonstration, I directly use the platform online service. Official website address:

https://www.showdoc.com.cn/item/index

You can use the markdown grammar to write API documents, data dictionary documents, technical documents, and online excel documents. But senior lazy programmers like me, in fact, pay more attention to showdoc , which can automatically generate API documentation from code comments, or use the RunApi client (similar to postman's api debugging tool). Debug interface and automatically generate documents on the same side.

Let’s demonstrate from the beginning, let’s take a look at where is this thing useful?

First acquaintance with ShowDoc

ShowDoc New projects can choose regular API documents, online forms, or single-page documents (directory hierarchy is not supported), allowing you to set access passwords for project documents, and customize domain names. This is not a real "domain name", just A first-level directory is added after the document service domain name, for example:

www.showdoc.com.cn/程序员内点事

You can copy existing projects, or directly import Postman , swagger API interface configuration Json files. The open API provided is the key to automatic document generation. First, remember that there are two attributes, api_key and api_token

After entering the project, click + upper right corner to edit the document. ShowDoc has several document templates preset, and you can also save the customized document as a template; support online Mock service, define the data format of the interface in advance, and provide an online temporary interface first , In this way, it can be developed synchronously with the front-end and switch seamlessly afterwards; there is also a simple API online test function.

The online table style is very concise

There are two formats for exporting documents: word and Markdown

Support version control, you can see the record of each modification, and roll back the modification of any version.

When sharing online documents with others, if you don't want to expose the entire API catalog, you can choose to share on a single page.

Seeing this, it feels like showdoc is very common. It seems that there is nothing special. The above documents need to be written manually. It is more cumbersome and not recommended. Next, let's take a look at how to automatically generate documents.

Automatically generate documentation

showdoc has three ways to automatically generate API documentation:

• Use Runapi tool to automatically generate ( recommended )
• Automatic generation of program code comments
• Automatically generate data dictionary
• Write your own program to call the interface to generate

Runapi tool

Runapi is a development and testing tool with interface as the core (it can be regarded as a streamlined version Postman The client currently supports the win , mac , linux platform and online version, including interface testing, automatic process testing, mock data, project collaboration and other functions.

The simple Runapi and Postman little advantages compared with showdoc , but it is more efficient when used with runapi testing the interface with 060f0f64609b43, it will automatically generate API documents to showdoc . It can also share showdoc to achieve multi-person collaboration.

Runapi client can create API interface documents with debugging, or documents in Markdown format.

For example, we create a new project " programmers do something", respectively build three interfaces " point", " is watching", " attention", and then quickly generate parameters and response result data and save.

document link in the upper right corner to set the access password. If it is not filled in, it is public by default. Copy the document link and open it in the browser. You can see that the API interface document has been generated. Runapi also has global parameters and environmental isolation. In fact, Postman also supports this function, but it is not a domestic product after all, and network access is very restricted.

There is also a better place. Runapi supports scripts before and after interface execution, such as assertion testing of response data, and the pop-up display is very easy to use.

Code comment

Writing the interface information in the comments can also automatically generate the document to showdoc , but I don't like this, mainly because it is more intrusive, which makes the code readability worse, and it looks very uncomfortable.

    /**
    * showdoc
    * @catalog 测试文档/用户相关
    * @title 用户注册
    * @description 用户注册的接口
    * @method post
    * @url https://www.showdoc.com.cn/home/user/login
    * @param username 必选 string 用户名  
    * @param password 必选 string 密码  
    * @param name 可选 string 用户昵称  
    * @return {"error_code":0,"data":{"uid":"1","username":"12154545","name":"吴系挂","groupid":2,"reg_time":"1436864169","last_login_time":"0"}}
    * @return_param groupid int 用户组id
    * @return_param name string 用户昵称
    * @remark 这里是备注信息
    * @number 99
    */
    public Object register(){

The implementation of this method is also relatively simple. Remember the api_key and api_token mentioned earlier. Now they come in handy. Below I will use the windows environment to demonstrate.

First, there must be a git environment locally:

https://npm.taobao.org/mirrors/git-for-windows/v2.17.0.windows.1/Git-2.17.0-64-bit.exe

Download the script officially provided by showdoc

https://www.showdoc.cc/script/showdoc_api.sh

Modify showdoc_api.sh and replace our api_key and api_token variable values. If the URL has not been built for your own document service, you don’t need to change it.

Put showdoc_api.sh in your project directory, double-click to run it directly, the script will automatically recursively scan all text code files in this directory and subdirectories, and generate API documents.

The document generated by showdoc_api.sh will be put into the project api_token

Generate data dictionary

If we want to generate a data dictionary document directly from the database dictionary table, showdoc is also supported, first download the official script

wget https://www.showdoc.cc/script/showdoc_db.sh

Modify the configuration in the script, the database, api_key , api_token and other information, after the direct execution, the database table structure information is synchronized to showdoc .


Variable names and explanations configured as follows


The effect is as shown in the figure below, a data table dictionary document is generated, which is very convenient in some specific scenarios.

Open API

showdoc opened the document editing API, we can call the API in the code to create and edit documents. The scenarios used in this way are more flexible.

https://www.showdoc.cc/server/api/item/updateByApi

The API parameters are as follows, the content of the document, the text in markdown format or the html source code can be passed.

Test the necessary parameters for interface assembly and send it with a simple online API debugging tool

{
  "api_key": "8e52cbad736aa9832b92acc4b34a830e961861279",
  "api_token": "9dcd8333afa7cde63bf84f8f0db5d2b2116079256",
  "page_title": "xiaofu",
  "page_content": "nihao"
}


See showdoc corresponding project already created a name for xiaofu documents.


Say a few words

He said front showdoc existing functionality postman basic support, but postman function too complicated simple enough, plus network conditions, and many other restrictions, coordination office efficiency is not high, but Runapi with showdoc can to a large extent in some scenarios Improve the efficiency of our development and delivery, so the ones that can be automatically generated are absolutely not handwritten!

No matter how BB brags, it’s pale, it’s easy to use, it’s suitable for you, and it’s clear at a glance.

I'm Xiaofu, see you next time~

I have compiled hundreds of technical e-books for students in need. The technology group is almost full, students who want to join can add my friends and blow up the technology with the big guys.

E-book address