Hello, everyone. I’m Xiao Fu

A few days ago, some friends in the fan group asked, what good API document tool recommendation, accidentally found a tool, here non-stop to share with you.

ShowDoc, a great online API documentation tool for teams, also supports the custom documentation service with Docker, but for the sake of demonstration, I used the platform online service directly. Official website address:

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

You can use Markdown syntax to write API documents, data dictionary documents, technical documents, online Excel documents. But for a veteran lazy programmer like me, it’s ShowDoc’s ability to generate API documents automatically from code comments, or with a RunAPI client (a Postman-like API debugging tool) that automatically generates documents while debugging the interface.

So let’s do it from the beginning, and let’s see how this works.

I met ShowDoc

ShowDoc creates a new project with the option of a regular API document, an online form, or a single page document (directory layering is not supported). It allows you to set an access password to the project document and customize the domain name. This is not a “domain name” in the true sense, but adds a level of directory after the document service domain name, such as:

www.showdoc.com.cn/ Programmers have something to do

You can copy an existing project, or import the PostMan, Swagger API directly to configure the JSON file. The provided open API is the key to automate document generation. Keep in mind that there are API_KEY and API_TOKEN attributes, which will be discussed in detail later.

After entering the project, click the top right corner + edit document. ShowDoc presets several document templates, and you can also save customized documents as templates. Support online Mock services, define the data format of the interface in advance, provide online temporary interface first, so that you can synchronize development with the front end, and then switch seamlessly; There is also a simple API online testing feature.

The online form style is simple

Export documents are available in Word and Markdown formats.

Support version control, can see the record of each change, rollback any version of the change.

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

It seems that there is nothing special about showDoc. These documents need to be written by hand, which is quite tedious and not recommended. Let’s take a look at how to automate the document generation.

Automatic document generation

ShowDoc has three ways to automatically generate API documents:

  • Automatically generate using the RunAPI tool (recommended)
  • Automatically generated using program code comments
  • Automatically generate data dictionary
  • Write your own program to call the interface to generate

Runapi tools

RunAPI is an interface-centric development and testing tool (think of it as a lite version of PostMan). At present, the client supports Win, Mac, Linux platform and online version, including interface testing, automatic process testing, Mock data, project collaboration and other functions.

RunAPI alone does not have much advantage over Postman, but it is more efficient when used with showDoc. When using RunAPI to test the interface, it will automatically generate API documents to showDoc, and it can also share the team management mechanism of showDoc to achieve multi-person collaboration.

The RunAPI client can create an API interface document with debugging, or one in Markdown format.

For example, we create a new project “Programmer In-Point”, respectively build three interfaces “In-Point”, “Looking” and “Concern”, and then quickly generate and save parameter and response result data.

Click on the top right corner of the document link set access password, do not fill in the default is public, copy the document link in the browser to open, see the API interface document has been generated. RunAPI also has global parameters, environment isolation. In fact, Postman also supports this function, but it is not a domestic product, network access and other aspects are very limited.

Another nice thing about RunAPI is that it supports scripts before and after interface execution, such as assertion tests for response data, and pop-up displays.

Code comments

Writing the interface information in the comment can also automatically generate a document to showDoc, but I don’t like this, mainly because it is more invasive, making the code less readable, and the glop looks very uncomfortable.

/** * showDoc * @Catalog Test Documentation/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 Object register(){

The implementation of this way is also relatively simple, remember the previous mentioned API_KEY, API_TOKEN these two attributes, now come in handy, I use the Windows environment demo.

First, you should have 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 provided by showdoc

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

Modify showdoc_api.sh and replace the values of our api_key and api_token variables. The URL does not need to be changed if you do not build your own document service.

Put showdoc_api.sh in your project directory, double-click to run it, and 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 placed in the project where you filled in the api_token.

Generate data dictionary

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

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

Modify the configuration in the script, database, API_KEY, API_TOKEN and other information, and synchronize the database table structure information to showDoc after direct execution.



Variable names and explanations for the following configuration

The result is a table dictionary document like the one shown below, which is handy for some scenarios.

Open API

ShowDoc opens up the document editing API, we can call the API in the code to create and edit the document. This allows for a more flexible scenario.

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

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

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

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



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

Say two words

As mentioned above, Postman basically supports the existing functions of ShowDoc, but Postman’s functions are too complicated and not simple enough. In addition, there are many limitations such as network conditions, so the efficiency of collaborative working is not high. However, RunAPI with ShowDoc can greatly improve the efficiency of our development and delivery in some scenarios. So can automatically generate absolutely not handwriting!

No matter how BB boast is pale, good or not, suitable for their own, do it at a glance

I’m Xiao Fu. See you next time

Organized hundreds of various technical e-books, students who need to help themselves. The technology group is nearly full, the students who want to enter can add my friend, and the big guys together blow the technology.

E-book address