Write API documents first or code first?

The code is not moving , Document first

In fact, we all know  API  The importance of document first , But in the process of practice, we often encounter many difficulties .

Two things programmers hate most ：1. Written document ,2. Others don't write documents . Most developers don't want to write API The reason for the document is The short-term benefits of writing documents are far less than the costs , However, not everyone can insist on doing Long term benefits Of things .

As a Fore and aft end separation Pattern development team , We often see such scenes ： Front end development and back-end development are discussed together “ How did your interface parameters change again ？”,“ Why doesn't the interface work again ？”,“ wait a moment , I'll debug ”,“ You try again ...".

Can you write it well API file , Everyone develops according to documents ？ It is difficult to , Because writing documents 、 Maintaining documents is troublesome , And it takes time , There will often be API Updated , But the document is still old , All kinds of synchronization inconsistencies , To delay each other's time .

Our team had the same problem before , So as the head of the R & D team , How did I lead the team to solve this problem ？

How to do ？

The method is actually very simple , If you can do it, let me write documents / Maintaining documents is a matter of Short term gains Can be much higher than The cost , Then all the problems can be solved , Developers will be happy to write interface documents .

The original working mode of the team

1. API The designer Use Swagger Write API file

2. The front-end development   Use mock.js  mock fake API data

3. The backend development   Use Postman debugging API

4. Testers   Use JMeter test API

The problem we've had

1. Our team enters the development at the front and back end simultaneously , You can't wait until the back-end development is completed to issue the interface document , The front end enters the development stage , So back-end code annotations are used to automatically generate Swagger Not for us .

2. Write Swagger Document efficiency is low , And there is a learning threshold , Let everyone in the team write skillfully Swagger Documentation is unrealistic , What's more, there are new people in the team .

3. Developers in Swagger After defining the document , Interface debugging also needs to go Postman Define it again .

4. The front-end development  Mock When it comes to data mock Define it in the tool , Set it manually Mock The rules .

5. Testers need to go to JMeter Define it again .

6. Front end according to mock The data from the tool has been developed , Back end according to Swagger The defined interface document is developed , Each test passed , I thought I could go online right away , As a result, a variety of problems were found ： Interface changes in the original development process , Only modified Swagger, But they didn't synchronize the changes in time mock.

7. Again , Test in JMeter Well written test cases , When it's really running, you'll find all kinds of inconsistencies .

8. The development process , It is often found that the interface document defined at the beginning is unreasonable , Need temporary adjustment , Interface changes often occur , But the document was not updated .

9. Time is long. , The inconsistencies will get more and more serious .

How to solve

It is necessary to write documents and maintain documents in time Short term gains Can be much higher than The cost , It's just two directions ：

1. Reduce the cost of writing documents

2. Increase the benefits of writing documents

In view of this , We imagine that it would be great if there was a tool to do the following ？

1. With Full Visualization Interface to write documents , And zero learning cost , New people   You can get started .

2. Data structures that can be defined through interface documents Automatically mock Data , No need   The front-end development   To write mock The rules , Go straight to work .

3. The backend development   Debug the interface based on the interface document , Without going to Postman Debugging ; If the interface changes , When debugging, the document is automatically updated , Zero cost ensures the timeliness of interface maintenance ; Automatically check the data structure according to the document , No visual verification is required , No need to write assertions manually .

4. The backend development   Each time a function is debugged, it is saved as a Interface use cases .

5. Testers   Use it directly Interface use cases Test interface .

6. Testers   More interface documents automatically generate test cases , And then like JMeter Just test it directly on it .

7. According to the data structure defined in the interface document , Automatic generation of front and rear Data model Code .

Sum up , What we need is such a tool ：

Through a system 、 A piece of data , Solve the problem of data synchronization between multiple systems . Just define the interface document , Interface debugging 、 data Mock、 Interface testing can be used directly , There is no need to redefine ; Interface documentation and interface development debugging use the same tool , After the interface debugging is completed, it can ensure that it is completely consistent with the interface document definition . Efficient 、 In time 、 accuracy ！

So , We have tasted almost all the relevant tools on the market , But unfortunately , Didn't find the right one .

What do I do ？ Do it yourself ！

therefore , We've achieved a Postman + Swagger + Mock + JMeter

This tool is  Apifox, Often after a long period of continuous updating iterations , We have basically fully realized the original idea , Almost perfectly solved all the problems encountered at the beginning , Very popular within the company . And we have formed our own best practices .

Best practices

1. front end （ or Back end ） stay  Apifox  It's fixed Interface document first draft .

2. Front and rear ends   Review together 、 perfect Interface document , reach a decision Interface use cases .

3. front end   Use  Apifox  Automatically generated  Mock data Entry into development , Without handwriting mock The rules , Go straight to work .

4. Back end   Use Interface use cases   Debug the interface in development , The system is defined according to the interface document Automatic verification Whether the returned data is correct , As long as all interface use cases are debugged , The interface development is completed .

5. Back end   After development , Testers （ It can also be Back end ） Use Set test Function for multi interface integration test , Completely test the whole interface call process .

6. Front and rear ends   All developed , Front end from Mock data Switch to Official data , Joint commissioning usually goes very smoothly , Because both the front and back sides fully comply with the specification of the interface definition .

Apifox Solution

One 、 How to solve these problems

1、Apifox location

Apifox = Postman + Swagger + Mock + JMeter

Apifox yes API file 、API debugging 、API Mock、API Automated testing integrated collaboration platform .

Through a system 、 A piece of data , Solve the problem of data synchronization between multiple systems . Just define the interface document , Interface debugging 、 data Mock、 Interface testing can be used directly , There is no need to redefine ; Interface documentation and interface development debugging use the same tool , After the interface debugging is completed, it can ensure that it is completely consistent with the interface document definition . Efficient 、 In time 、 accuracy ！

2、Apifox Purpose

Save every minute of the R & D team ！

3、Apifox function

1. Interface design ：Apifox Interface documentation follows OpenApi 3.0 ( primary Swagger)、JSON Schema At the same time , It's very easy to use visualization Document management function , Zero learning cost , Very efficient . And support online sharing of interface documents .

2. Data model ： Reusable data structure , Defining interfaces Return data structure And Request parameter data structure （ only JSON and XML Pattern ） You can directly reference . Support model direct nested reference , direct JSON/XML Smart import , Support oneOf、allOf And other advanced combination modes .

3. Interface debugging ：Postman Some functions , For example, environment variables 、 In front of / Post script 、Cookie/Session Global Shared And so on ,Apifox There are , And ratio Postman More efficient and easy to use . After the interface runs, click Save as use case Button , It can generate Interface use cases , Interface use cases can be run directly later , No more parameters need to be entered , Very convenient . Custom script 100% compatible Postman grammar , And support running javascript、java、python、php、js、BeanShell、go、shell、ruby、lua And other language codes .

4. Interface use cases ： Usually, an interface has multiple use cases , such as The parameters are correct Use cases 、 Parameter error Use cases 、 Data is empty Use cases 、 Different data states Use cases, etc . The correctness of data will be automatically verified when running the interface case , Using interface use cases to debug interfaces is very efficient .

5. Interface data Mock： built-in Mock.js Rules engine , Very convenient mock All kinds of data , And you can define the data structure and write mock The rules . Support adding “ expect ”, According to the request parameters, different mock data . most important of all Apifox  Zero configuration   that will do Mock Very human data , The details are introduced later in this paper .

6. Database operation ： Support reading database data , Used as an interface request parameter . Support reading database data , Used to verify ( Assertion ) Whether the interface request is successful .

7. Interface automation testing ： Provide interface set testing , You can choose the interface （ Or interface use cases ） Quickly create test sets . At present, more functions of interface automation test are still under development , Coming soon ！ The goal is ：JMeter Some functions are basically , And use it better .

8. Quick debugging ： similar Postman Interface debugging mode , It is mainly used for temporary debugging No documentation required The interface of , You can quickly debug without defining the interface in advance .

9. Code generation ： Define according to the interface and data model , Automatic system generation Interface request code 、 Front end business code And Back end business code .

10. Teamwork ：Apifox Born for teamwork , Interface cloud real-time synchronous update , ripe The team / project / Member rights management , Meet the needs of various enterprises .

Two 、Apifox It's not just about getting through the data

If you think Apifox We just got the data through , To improve the efficiency of the R & D team , It would be wrong .Apifox And a lot of innovation , To improve the efficiency of developers .

1、 Interface support “ Use case management ”

Usually, an interface has multiple use cases , such as   The right use case   Parameter error use case   Data is empty use case   Different data state use cases . Define these different states of use cases when defining interfaces , Interface debugging directly run , Very efficient .

2、“ Data model ” Definition 、 quote

Data models can be defined independently , The data model can be referenced directly when defining the interface , Data models can also refer to each other . Same data structure , Just define it once and use it in many places ; Only one modification is needed , Multiple live updates , Avoid inconsistencies .

3、 During debugging “ Automatic verification ” data structure

Use Apifox When debugging the interface , According to the definition in the interface document , Automatically check whether the returned data structure is correct , It is not necessary to identify with the naked eye , There is no need to manually write assertion scripts to detect , Very efficient ！

Apifox Automatic verification of data structures

4、“ visualization ” Set assertion

Set assertion ：

Apifox Set assertion

After operation , Look at the assertion results ：

5、“ visualization ” Set extraction variables

6、 Support database operations

7、“ Zero configuration ”Mock Very human data

Let's start with a picture Apifox And other similar tools   Zero configuration  mock The result of the data is ：

Apifox Mock Data results compared with similar tools

It can be seen that Apifox  Zero configuration  Mock The data is very close to the real situation , Front end development can use , You don't have to write it manually mock The rules .

Apifox How to do high efficiency 、 Zero configuration It's very human mock data

1. Apifox According to the data structure in the interface definition 、 data type , Automatic generation mock The rules .

2. Apifox Built in intelligence mock Rule base , According to the field name 、 Field data type , Intelligent optimization automatically generated mock The rules . Such as ： The name contains the string image Of string The type field , Automatically mock Give a picture address URL; Include string time Of string The type field , Automatically mock Give a time string ; Include string city Of string The type field , Automatically mock Name a city .

3. Apifox According to the built-in rules , Can automatically identify pictures 、 Head portrait 、 user name 、 cell-phone number 、 website 、 date 、 Time 、 Time stamp 、 mailbox 、 Province 、 City 、 Address 、IP Etc , thus Mock Very human data .

4. In addition to the built-in mock The rules , Users can also customize the rule base , Meet a variety of personalized needs . Support use   Regular expressions 、 wildcard   To match field name customization mock The rules .

8、 Generate online interface documentation

Apifox Project can “ Share online ” API file , Shared API Documents can be set to public or require password access , It's very convenient to work with external teams .

Experience address ：https://www.apipark.cn/s/ce387612-cfdb-478a-b604-b96d1dbc511b/http/5041285

9、 Code auto generation

Define according to the interface model , Automatic generation of various languages / frame （ Such as TypeScript、Java、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rust etc. ） Business code of （ Such as Model、Controller、 Unit test code, etc ） And interface request code . at present Apifox Support 130 Code generation for languages and frameworks .

what's more ： You can go through Custom code template To generate code that meets your team's architectural specifications , Meet a variety of personalized needs .

10、 Import 、 export

1. Support export  OpenApi (Swagger)、Markdown、Html  And so on , Because you can export OpenApi Format data , So you can use OpenApi (Swagger) Rich ecological tools to complete a variety of interface related things .

2. Support import  OpenApi (Swagger)、Postman、HAR、RAML、RAP2、YApi、Eolinker、NEI、DOClever、ApiPost 、Apizza 、ShowDoc、API Blueprint、I/O Docs、WADL、Google Discovery And so on , Facilitate the migration of old projects .

3、 ... and 、 Follow up function planning

1. Release Apifox WEB edition , Support the use of... On the browser side Apifox.

2. Interface performance test support （ similar JMeter）.

3. Support plug-in market , You can develop your own plug-ins .

4. to open up Apifox API, Allow developers to pass through API call Apifox The function of .

5. Support more interface protocols , Such as GraphQL、gRPC、websocket etc. .

6. Support offline use , Project can choose online synchronization （ Teamwork ） Or just local storage （ Stand alone offline use ）.

Four 、 more Apifox Function screenshot

Interface design Interface debugging Customize mock The rules intelligence mock Interface automation Import the project Project export Multiple themes are optional

5、 ... and 、 Apifox Download address

The software is completely free , Copy the link below , Paste it into the browser and open it to download . Official website address ：www.apifox.cn