Interface document evolution atlas, some ancient interface document tools, you may not have used them

​

Maybe today's little programmers hear that someone has used it before word To do interface documentation , You'll be surprised , But in the early stage of the implementation of front and rear end separation , There are really not so many handy interface documentation tools .

The Internet has developed to the present , Interface documents have also experienced from simple word To markdown, To swagger, To Apifox And so on , Become more and more beautiful , More and more standardized , It also supports more and more function assisted debugging .

Next, let's review the evolution of interface documents over the years .

​

edit

One 、 Juvenile of interface document ：word

​

edit

At first, the front and rear ends are separated , The back-end has to inform the front-end interface of various information , Convenient for front-end call . That's all the information you need to provide , Just use word Write it , So there is such an interface document ：

​

edit

The problem seems to have been solved , But the project , It is constantly modified and iterated , And that leads to ：

This interface document is frequently changed with the project . Every update , You need to distribute a new interface document to the project members

therefore ： A. Every time you make a change, you need to create a new one , Copy it to many people in the project team , Such a document is copied around , There are so many people in the project team , No one knows whether they got a brand new version ;

B. If you change a little, you need to generate a new document , So the interface document in the folder may be in this form ：

​

edit

I won't say who cried .

These pain points contributed to the first evolution of interface documents ： from word Version of the interface document evolved into a web version of the interface document .

Two 、 Growth body of interface document ：Markdown

​

edit

How perfect the interface document of the web version , Just distribute a link to the project members to save .

such , If the back end modifies the interface , Modify directly in the web page , Just make sure that what you see is the latest version , There is no need to send a new document to everyone every time there is a change .

Such a is made up of markdown Generated static html page , The key elements of an interface are all

​

edit

Problem solving ！

but —— New problems arise again .

This interface document is available , But it's not so easy to use , for instance ：

1. Writing interfaces is troublesome , Completely written by hand , There are no auxiliary tools , It takes a lot of time

2. The effect of the generated interface document cannot be seen immediately after the interface is written , If you make a mistake, you have to adjust it again

3. There are no interface specification constraints , How to write interface documents , Which parameters should be written , Which are not written , The presentation form depends on the developer's own business level .

So a new round of evolution began —— Someone developed a tool , It is specially used to write interface documents .

3、 ... and 、 The whole interface document ：swagger

​

edit

How to write ？ stay swagger editor Written in line with swagger Interface document of syntax , To generate interface documents , The interface document can be written in swagger editor Live preview on the right side of ：

Uploading … Re upload cancel

therefore , The interface documentation tool that evolved to this full body stage has achieved the following functions ：

1. The online viewing function supported by the web interface document , Of course, he also has , And the style of this interface document is consistent with open api3.0 canonical , If it doesn't conform to grammar ,swagger editor Will also report errors to correct you .

The information that a standard interface should have ： Interface method 、 Interface path 、 Request and response parameters , Can be presented in a fixed format .

​

edit

2. It also has a preliminary 、 Simple debugging function , That is, the interface request parameter is a space , Fill in the parameters 、 Send a request , You can return the response parameters

​

edit

It seems to be enough, right ？

but —— wait , If these are developed by yourself, it's OK to use them alone , But if you want to apply it to the project , So many interface documents , It's quite difficult to manage ,swagger editor Do not provide project level archiving and management , Maintenance is also troublesome .

and , up to now , Nor has it escaped the fate of relying on handwriting to generate interface documents , And to learn swagger annotation , thus , Learning costs have , Work efficiency cannot be improved .

Generated interface documents , The front end needs to use interface information to debug the page , The test will use it to verify the interface . But at present, the functions of interface documents , Support for front-end and test work is not enough ~

As if .... It can also be more perfect ？？！

If there is a pain point, there will be a solution , So the interface document starts a new round of evolution , The interface document tool for entering the extreme evolution form is ——

Four 、 The ultimate evolutionary form of interface documents ：Apifox

​

edit

​

edit

Want teamwork ？ arrange . You want to generate interface documents without writing code ？ Sure . You want to debug the interface directly on the interface document ？ Support . The interface has not been put into the production environment 、 But if you want to simulate data, you can debug the front-end page ？ Support . Want to use interface data directly to do automated testing ？ arrange .

​

edit

So an interface document tool that studies the extreme evolution form was born .

The first is to optimize the functions of existing interface documents ：

A. Visual interface design page , Do not write swagger annotation , After filling in the parameters, saving is an interface document .

As long as you know the knowledge of interface, you can write by hand , Rounding this learning cost is zero .

​

edit

Interface document editing status

​

edit

The interface document is read-only

B. One click export interface document , Only some interface documents can be shared , Set expiration time , Set the password

​

edit

C. The interface document is updated in real time Once the interface document changes , The data will be synchronized to all members of the project in real time

The second is to add plug-ins to the front-end and testing crazily ：

A. The interface document page supports online debugging

​

edit

The shared interface document page supports simple basic debugging functions , If you want more powerful debugging assistance , You can use Apifox client .

The debugging function of the client is to extract variables 、 Assertion 、 Functions such as connecting to the database are visually encapsulated , Don't write scripts , If There are complex debugging requirements , Script debugging is still supported

​

edit

B. Support code generation There are many kinds of code supported , Including various languages and frameworks commonly used in the front and back end , All in all 130 Varied ,javascript and swift,java And so on, the generated front-end code can be copied .

​

edit

It not only supports the generation of interface request code , It also supports generating data model code , The code of the whole project , Can be generated on demand , Then adjust yourself , In this way, the amount of code that needs to be written is greatly reduced .

​

edit

F. Provide mock Environmental Science The interface request can also be simulated when the interface is not online , Construct highly authentic business data for front-end test pages , Back end 、 Test to debug and test the interface

​

edit

You can copy links to the browser to view the generated online documents ：

https://www.apifox.cn/apidoc/shared-cbb5c14c-0faa-4b4d-9f6e-7027cd57c702/api-21636796

Finally, integrate the whole work chain of the interface into its tool ：

A. Support project level collaboration

Each interface belongs to a different module , Belong to different directories . Back end 、 front end 、 The test can use the same set of interface data sources , That is to say, after the interface is created , The back end is maintained on it , The front end uses it as the interface mock, Testing uses it for interface automation , Data changes are synchronized to each end in real time , There is no need to switch multiple software .

​

edit

B. Support import postman,swagger Wait up to 20 Interface data in various formats , Realize project migration at zero cost

​

edit

C. Support export swagger,html,word Format interface document , Nor kidnap users , If you want to migrate to other systems, it's also generous to complete you .

​

edit

Such a set of combined punches , Basically, it has all the functions you can think of in the interface document .

Official website address ：www.apifox.cn

summary

therefore , Sum up , Interface documents have always been evolving , Combat effectiveness is also getting stronger , It also provides more and more help for R & D personnel , Let them write less unnecessary code , Do less repetitive work . According to the actual situation of your project , Choose the right tools .

​