This article is available at github.com/chengxy-nds…

Hello, I’m Rich

A few days ago, some friends in the fan group asked, what is the recommended API document tool, accidentally found a tool, here to share with you without a stop.

ShowDoc is a great online API documentation tool for teams. It also supports docker’s own documentation service, but for the sake of demonstration, I used the platform’s online service directly. Official website address:

https://www.showdoc.com.cn/item/index
Copy the code

You can use markdown syntax to write API documents, data dictionary documents, technical documents, and online Excel documents. But for seasoned lazy programmers like me, it’s showDoc’s ability to automatically generate API documentation from code comments, or with the RunApi client (a Postman-like API debugger) to automatically generate documentation as you debug your interface.

So let’s go back to the beginning and see what this thing is good for.

I met ShowDoc

ShowDoc creates new projects with regular API documents, online forms, or single-page documents (directory hierarchy is not supported), allowing access to project documents with passwords and custom domain names. This is not a “domain name”, just a level of directory after the document service domain name, for example:

www.showdoc.com.cn/ programmer internal mattersCopy the code

You can copy existing projects or directly import Postman, Swagger API configuration Json files. The provided open API is the key to automated document generation. Keep in mind the api_key and API_token attributes, which will be covered later.

After entering the project, click on the upper right corner + edit document. ShowDoc presets several document templates and can also save custom documents as templates. Support online Mock service, define the data format of the interface in advance, provide online temporary interface first, so that it can be synchronized with the front-end development, and then seamless switch; There is also a simple API online testing function.

The online form style is neat

The exported document can be in Word or Markdown format.

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

If you don’t want to expose the entire API directory when sharing online documents with others, you can choose to do single-page sharing.

Showdoc is very common, it seems that there is nothing special, the above documents need to be written manually, it is not recommended to do so, let’s see how to automate the generation of documents.

Automatic document generation

Showdoc automatically generates API documentation in three ways:

  • Automatic generation using Runapi tool (recommended)
  • Automatically generated using program code comments
  • Automatic data dictionary generation
  • Write their own procedures to call the interface to generate

Runapi tools

Runapi is an interface – centric development test tool (think of it as a lite version of Postman). Currently, the client supports Win, MAC, Linux platforms and online versions, including interface testing, automatic process testing, Mock data, project collaboration and other functions.

Runapi is not superior to Postman alone, but it is more efficient to use with ShowDoc. When testing the interface with Runapi, it will automatically generate API documents to ShowDoc. It can also use ShowDoc’s team management mechanism to achieve multi-person collaboration.

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

For example, we created a new project “Programmer internal point”, respectively set up three interfaces “point in”, “look at”, “pay attention to”, and then quickly generate parameters and response result data and save.

Click the document link in the upper right corner to set the access password. If you do not fill in the password, the default is public. Open the copy document link in the browser and see that the API interface document has been generated. Runapi also has global parameters and environment isolation. Postman also supports this function, but it is not a domestic product, and Internet access is limited.

On the plus side, Runapi supports pre – and post-interface scripting, such as assertion tests for response data, and pop-ups, which are useful.

Code comments

Writing interface information in comments can also automatically generate documentation to ShowDoc, but THIS is not my favorite, mainly because it is more intrusive and makes the code less readable, which makes it very uncomfortable to look at.

/** * showdoc * @catalog test document/user related * @title user registration * @description user registration interface * @method post * @URL https://www.showdoc.com.cn/home/user/login * @ param username will choose string username * @ param password will choose string password * @ param name Optional string User nickname * @RETURN {" error_code ": 0," data ": {" uid" : "1", "username" : "12154545", "name" : "hang wu", "groupid" : 2, "reg_time" : "1436864169", "last_login_tim E ":"0"}} * @return_param groupid int user groupid * @return_param name string user nickname * @remark remarks * @number 99 */ public Object register(){Copy the code

Api_key, api_token, api_token, token, token, token, token, token, token

First, you need a local git environment:

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

Download the script provided by Showdoc

https://www.showdoc.cc/script/showdoc_api.sh
Copy the code

Change showdoc_api.sh to replace the api_key and API_token values.

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

Showdoc_api.sh generates the document that goes into the project where you filled in the API_token.

Generate data dictionary

If we want to generate data dictionary documents directly from the database dictionary table, showdoc also supports this, download the script provided by the official

wget https://www.showdoc.cc/script/showdoc_db.sh
Copy the code

Modify the configuration of the database, API_key, and API_token in the script. After the script is executed, the database table structure is synchronized to showdoc.

The variable names and explanations are as follows

The result is a data table dictionary document like the one shown below, which can be handy in certain scenarios.

Open API

Showdoc opens up a document editing API that you can call in your code to create and edit documents. This allows for more flexibility in the use of scenarios.

https://www.showdoc.cc/server/api/item/updateByApi
Copy the code

The API parameters are as follows: document content, text in Markdown format, or HTML source code.

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

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

See inshowdocThe corresponding project has been created with the namexiaofuThe document.

Say two words

As mentioned above, Postman basically supports all the existing functions of Showdoc, but postman’s functions are too complex and not simple, coupled with network conditions and other restrictions, the efficiency of collaborative office is not high, while Runapi and Showdoc can greatly improve the efficiency of our development and delivery in some scenarios. So can automatically generate absolutely no handwriting!

How BB boast again is pale, good use, suit oneself, begin to do clear at a glance

I’m rich. See you next time

I have sorted out hundreds of technical e-books for students who need them. The technology group is almost full, want to enter the students can add my friend, and the big guys blow technology together.

Ebook address