Two things programmers hate most: 1. Write documentation, and 2. Other people don’t write documentation. The reason most developers don’t want to document apis: The short-term benefits of documenting far outweigh the costs, but not everyone can stick with something that has long-term benefits. If you delay your current project by writing a document, your boss will come after you directly. But the long-term benefits of not writing documentation are low and invisible to the boss. That’s the reality. It’s very difficult to get people to do things against humanity.

As a front – and back-end development team, we often see a scene where the front – and back-end developers get together and have a heated discussion about “What’s wrong with your interface?” “, “Why is the interface broken again?” “, “Wait a minute, LET me debug it”, “Try again…” .

Can we write the interface documentation, and we all develop according to the documentation? It’s hard because it’s cumbersome to write and maintain documentation, and it’s time consuming, and there are often apis that are updated, but the documentation is still old, and all kinds of synchronization is inconsistent, which delays each other.

Our team also encountered the same problem before. As the head of the R&D team, how did I lead the team to solve this problem?

How to do?

The solution is simple: if you can make the short-term benefits of writing/maintaining documentation far outweigh the costs, all problems will be solved and developers will be more than happy to write interface documentation.

How the team used to work

  1. Write interface documents with Swagger
  2. The front-end development uses RAP Mock interface data
  3. Back-end development uses the Postman debugging interface
  4. Testers use JMeter to test the interface

The problems we have

  1. Our team entered the development synchronously at the front and back ends, and could not wait for the end to finish the development of the interface document, and then enter the development at the front end. Therefore, it is not suitable for us to automatically generate Swagger by using back-end code comments.
  2. It is very inefficient to write Swagger documents, and there is a learning threshold. It is unrealistic for all members of the team to write Swagger documents proficiently, let alone there are constantly new members in the team.
  3. After Swagger has defined the document, developers need to go to Postman to define it again during interface debugging.
  4. The front-end Mock data development needs to RAP again to define Mock rules manually.
  5. Testers need to go to JMeter to define it.
  6. The front-end was developed according to the data derived from RAP Mock, and the back-end was developed according to the interface document defined by Swagger. They passed their respective tests and thought they could be launched immediately. However, various problems were found in the first connection: in the original development process, the interface was changed and only Swagger was modified, but RAP was not timely synchronized.
  7. Similarly, the tests found various inconsistencies when JMeter’s written test cases were actually run.
  8. During the development process, it is often found that the interface document defined at the beginning has some unreasonable places and needs to be adjusted temporarily. It is often found that the interface is changed, but the document is not updated.
  9. Over time, the inconsistencies get worse and worse.

How to solve

The short-term benefits of writing and maintaining documentation far outweigh the costs in one of two ways:

  1. Reduce the cost of writing documentation
  2. Increase the revenue after writing the document

With that in mind, wouldn’t it be cool to have a tool that did the following?

  1. In order toComplete visualizationInterface to document, and zero learning cost,The coupleIt’s easy to get started.
  2. Data structures that can be defined through interface documentationAutomatic mockOutput data without having toThe front-end developmentTo writemockThe rules.
  3. The backend developmentDebug the interface based on the interface documentation without having to go toPostmanThe debugging; If the interface is changed, the document will be automatically updated during debugging, which ensures the timeliness of interface maintenance at zero cost.
  4. The backend developmentSave one function after each debuggingThe interface use cases.
  5. The testerDirect use ofThe interface use casesTest the interface.
  6. The testerMore interface documentation automatically generates test cases, then likeJMeterAs well as testing directly on top.
  7. The front and back ends are automatically generated based on the data structure defined by the interface documentThe data modelThe code.

All we need is a tool that:

It solves the data synchronization problem among multiple systems by using one set of systems and one piece of data. Once the interface documentation is defined, interface debugging, data Mock, and interface testing can be used directly without needing to be defined again. The interface documentation and interface development and debugging use the same tool, after the interface debugging can ensure that the definition of the interface documentation is completely consistent. Efficient, timely and accurate!

To do this, we tried almost every tool on the market, but unfortunately, we couldn’t find the right one.

How to do? Do yourself!

So, we implemented a Postman + Swagger + RAP + JMeter by ourselves

The tool was Apifox, and over a long period of iteration and iteration, we basically implemented the original vision, solved almost all of our initial problems perfectly, and became very popular within the company. And develop our own best practices.

Best practices

  1. The front end(orThe back-end) inApifoxOn the setInterface documentationThe first draft.
  2. Before and after the end of theReview and improve togetherInterface documentationGood,The interface use cases.
  3. The front endUsing the system according to the interface document automatically generatedThe Mock dataEnter development.
  4. The back-enduseThe interface use casesDebugging and development of the interface, the system according to the definition of the interface documentAutomatic calibrationWhether the returned data is correct, as long as all interface use cases debugging through, the interface development is completed.
  5. The back-endWhen the development is complete,The tester(It could also beThe back-end) to useA collection of testFunction for multi-interface integration test, complete test the whole interface call process.
  6. Before and after the end of theAll developed, the front end fromThe Mock dataSwitch to theOfficial data, syndication usually goes smoothly because both the front and back ends fully comply with the specification of the interface definition.

Foreign service

That’s right, now that we’ve productized Apifox to external services, your team can use Apifox directly.

Website: www.apifox.cn

Apifox solution

First, how to solve these problems

1. Apifox positioning

Apifox = Postman + Swagger + Mock + JMeter

It solves the data synchronization problem among multiple systems by using one set of systems and one piece of data. Once the interface documentation is defined, interface debugging, data Mock, and interface testing can be used directly without needing to be defined again. The interface documentation and interface development and debugging use the same tool, after the interface debugging can ensure that the definition of the interface documentation is completely consistent. Efficient, timely and accurate!

2. Purpose of Apifox

Save every minute of r&d team!

3. Apifox function

  1. Interface design: Apifox Interface documentOpenApi3.0 (formerly Swagger),JSON SchemaSpecification at the same time, provides a very usefulvisualizationDocument management function, zero learning cost, very efficient. It also supports online sharing of interface documents.
  2. The data model: reusable data structures that define interfacesReturn data structureandRequest parameter data structure(only JSON and XML schemas) can be referenced directly. Support model directly nested reference, direct JSON/XML intelligent import, support advanced combination modes such as oneOf and allOf.
  3. Interface debuggingApifox has all of Postman’s features, such as environment variables, pre/post scripts, Cookie/Session global sharing, and is much more efficient than Postman. Click after the interface runsSave as a use caseButton, can be generatedThe interface use cases, you can directly run the interface case without input parameters, which is very convenient. Custom scripts are 100% compatible with Postman syntax and can run javascript, Java, Python, PHP, JS, BeanShell, Go, shell, Ruby, Lua and other languages.
  4. The interface use cases: Usually an interface will have multiple case use cases, such asParameters correctlyUse cases,Parameter errorUse cases,Data is emptyUse cases,Different data statesUse cases and so on. It is very efficient to debug the interface with the interface use case.
  5. Interface data Mock: built-inMock.jsRules engine, which makes it easy to mock out data and write mock rules while defining data structures. Support for adding “expectations” that return different mock data based on request parameters. The most important is ApifoxZero configurationYou can Mock out very human data, as described later in this article.
  6. Database operation: Reads database data as interface request parameters. Support for reading database data to verify (assert) the success of an interface request.
  7. Interface automation testing: Provides interface collection tests that can be quickly created by selecting an interface (or interface use case). At present, more functions of interface automation testing are still under development, please look forward to it! The goal: To have almost all of JMeter’s features and make them better.
  8. Quick debugging: interface debugging mode similar to Postman, mainly used for temporary debuggingNo documentation requiredThe interface can be quickly debugged without defining the interface in advance.
  9. Code generation: Automatically generated by the system according to the interface and data model definitionInterface request code,Front-end business codeandBack-end business code.
  10. Team collaboration: Apifox is born for team collaboration, interface cloud real-time synchronization update, matureTeam/project/member permissionsManagement to meet the needs of various enterprises.

Apifox does more than just get through the data

It would be a mistake to think that Apifox only does data access to improve the efficiency of the r&d team. Apifox has also made a number of innovations to improve developer productivity.

1. Interface support “Use case Management”

Usually an interface will have multiple case use cases, such as correct use case parameters error use case data null use case different data state use case. Use cases of these different states are defined when defining the interface, and run directly when debugging the interface, which is very efficient.

2. “Data Model” definition and reference

Data models can be defined independently, directly referenced in interface definitions, and referred to each other. The same data structure, only need to define once can be used in multiple places; You only need to modify one place and update multiple places in real time to avoid inconsistency.

3, “automatic verification” data structure during debugging

When using the Apifox debugging interface, the system automatically verifies whether the returned data structure is correct according to the definition in the interface documentation. There is no need to visually identify the data structure, and no need to write the assertion script manually. Very efficient!

4. “Visualize” setting assertions

Set the assertion:

After running, see the result of the assertion:

5. “Visualize” setting extraction variables

6, support database operations

7. “Zero configuration” Mock out very human data

Here’s how Apifox and other tools mock out data with zero configuration:

As you can see, the Apifox zero-configuration Mock is very close to the real data, and front-end development can use it directly without having to write Mock rules manually.

How does Apifox do thatHigh efficiency,Zero configurationGenerate very user-friendly mock data

  1. Apifox automatically generates mock rules based on the data structure and data type in the interface definition.
  2. Apifox has a built-in smart Mock rule library that intelligently optimizes automatically generated mock rules based on field names and field data types. For example, the name contains a stringimagethestringType field, automatically mock out an image address URL; Contain stringtimethestringType field, automatically mock out a time string; Contain stringcitythestringType field that automatically mocks out a city name.
  3. Apifox can automatically recognize fields such as picture, profile picture, username, mobile phone number, URL, date, time, timestamp, email, province, city, address, IP and so on according to built-in rules to Mock out very human data.
  4. In addition to built-in mock rules, users can also customize a library of rules to meet various personalized requirements. Support the use ofRegular expression,The wildcardTo match the field name custom mock rule.

8. Automatic code generation

According to the interface model definition, Automatically generate business code (Model, Controller, unit test code, etc.) and interface request code in various languages/frameworks (TypeScript, Java, Go, Swift, ObjectiveC, Kotlin, Dart, C++, C#, Rust, etc.). Apifox supports automatic code generation for 130 languages and frameworks.

More importantly, you can customize code templates to generate code that conforms to your team’s architectural specifications for a variety of individual needs.

9. Import and export

  1. Supports exportOpenApi (Swagger),Markdown,HtmlData format, as can be exportedOpenApiFormat data, so you can take advantage of OpenApi’s (Swagger) rich ecosystem of tools to do all sorts of interface related things.
  2. Support for importingOpenApi (Swagger),Postman,HAR,RAML,RAP2,YApi,Eolinker,NEI,DOClever,ApiPost 、Apizza 、ShowDoc,API Blueprint,I/O Docs,WADL,Google DiscoveryAnd other data formats, convenient old project migration.

Iii. Follow-up function planning

  1. Interface documents are released to the public.
  2. Interface performance testing support (similar to JMeter).
  3. Support plug-in market, you can develop your own plug-ins.
  4. Supports more interface protocols, such asGraphQL,websocketAnd so on.
  5. Offline use is supported. The project can be synchronized online (for teamwork) or stored locally (for offline use on a single machine).

4. More Apifox screenshots

Apifox download address

Please visit the Apifox official website: www.apifox.cn/ interface documentation tool

This article is published by OpenWrite!