当前位置：网站首页>Do you write API documents or code first?

Do you write API documents or code first?

2022-06-30 18:22:00 【InfoQ】

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 team of front-end and back-end separation pattern development , 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

API The designer
Use
Swagger
Write API file

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

The backend development
Use Postman debugging API

Testers
Use JMeter test API

The problem we've had

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 .

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 .

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

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

Testers need to go to JMeter Define it again .

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.

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

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 .

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 ：

Reduce the cost of writing documents

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 ？

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

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 .

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 .

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

Testers
Use it directly
Interface use cases
Test interface .

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

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

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

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

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

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 .

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 .

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 .

2、Apifox Purpose

Save every minute of the R & D team ！

3、Apifox function

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 .

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 .

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 .

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 .

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 .

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 .

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 .

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 .

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
.

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 ！

4、“ visualization ” Set assertion

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 ：

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

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

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 .

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 .

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

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 .

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 .