Java interface document evolution history: liberate your hands step by step

At the beginning, the front and rear ends are separated, and the back end has to inform the front end of the information of the interface to facilitate the front end to call. That's all the information you need to provide, just write it in word, so you have this interface document:

The problem seems to be solved, but the project is constantly modified and iterated, which leads to:

This interface document changes frequently with the project. With each update, a new interface document needs to be distributed to project members

So:

a. Every time you change it, you have to create a new copy and copy it to many people on the project team. Such a document is copied over and over again. With so many people in the project team, no one knows whether they are getting a brand new version.

b. If you change it, a new document will be generated, so the interface document in the folder may be in this form:

I won't tell you who cried.

These pain points contributed to the first evolution of interface documents: from the word version of the interface document to the web version of the interface document.

Second, the growth of the interface document: Markdown

The web version of the interface document is so perfect that you only need to distribute a link to the project member to save it.

In this way, if the backend modifies the interface and modifies it directly in the web page, you can make sure that what you see is the latest version, and you don't have to send a new document to you every time there is a change.

For such a static html page generated by markdown, all the key elements of an interface have

Problem solved!

But-- a new problem arises.

This interface document works, but it doesn't work that well, for example:

1. Writing the interface is troublesome, completely handwritten, without any auxiliary tools, and takes a lot of time.

two。 After the interface is written, you can't immediately see the effect of the generated interface document. If you write it wrong, you have to go back and call it back.

3. There are no interface specification constraints, how to write the interface document, which parameters to write, which are not written, and how to present the form depends on the business level of the developer.

So a new round of evolution began-- someone developed a tool specifically for writing interface documents.

3. The complete interface document: swagger

How to write?

Write an interface document that conforms to the swagger syntax in swagger editor to generate the interface document, which can be previewed in real time on the right side of the swagger editor:

As a result, the interface documentation tool that has evolved to this entire stage has implemented the following functions:

1. The web version of the interface document supports online viewing function, of course, he also has, and the style of this interface document is in accordance with the open api3.0 specification, if the writing does not conform to the syntax, swagger editor will report an error to correct you.

The information that a standard interface should have, such as interface methods, interface paths, request and response parameters, can be presented in a fixed format.

two。 It also has a preliminary and simple debugging function, that is, if the API request parameter is blank, fill in the parameter and send the request, you can return the response parameter.

It seems to be enough, isn't it?

But-- wait, these are OK if they are developed for their own use, but if they are to be applied to the project, so many interface documents are difficult to manage. Swagger editor does not provide project-level archiving and management, and maintenance is also troublesome.

Moreover, so far, there is no escape from the fate of handwritten interface documents, but also to learn swagger notes, so that the cost of learning, work efficiency can not be improved.

The generated interface document, the front end needs to use the interface information to debug the page, and the test will use it to verify the interface.

But at present, the function of the interface document is not enough to support the front-end and testing work.

It seems. It can be more perfect?!

If there is a pain point, there will be a solution, so the interface document begins a new round of evolution, and the interface document tool to enter the extreme evolution form is--

Fourth, the extreme evolution of interface documents: Apifox

Want to work as a team? Make arrangements.

Want to generate interface documentation without writing code? Sure.

Want to debug the interface directly on the interface document? Support.

The interface is not on the production environment yet, but if you want to simulate the data, you can debug the front-end page? Support.

Want to do automated testing directly with interface data? Make arrangements.

As a result, an interface documentation tool for extreme evolution was born.

The first is to optimize the existing interface document function:

a. Visual interface design page, do not need to write swagger notes, fill in the parameters to save is an interface document.

As long as you know the knowledge of the interface, you can write by hand, and the learning cost is zero when rounded.

Interface document editing status

Interface document read-only status

b. One-click export interface documents, support sharing only part of the interface documents, set expiration time, set password

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 a crazy plug-in to the front end and test:

a. The interface document page supports online debugging

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

The debugging function on the client side visually encapsulates the functions such as extracting variables, asserting and connecting to the database. There is no need to write scripts. If there are complex debugging requirements, script debugging functions are still supported.

b. Support to generate code, support a variety of code types, including the front and back end commonly used in a variety of languages and frameworks, a total of more than 130, javascript and swift,java and so on generated front-end code replication can be used.

Not only support the generation of interface request code, but also support the generation of data model code, the code of the entire project can be generated as needed, and then adjust it yourself, so that the amount of code that needs to be written is greatly reduced.

c. Provide mock environment

The interface request can also be simulated when the interface is not online, and highly real business data can be constructed for the front-end test page, and the back-end and test for interface debugging and testing.

You can copy a link to a browser to view the resulting online document:

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

Finally, an entire working chain of the interface is integrated into it as a tool:

a. Support project-level collaboration, each interface belongs to a different module, belongs to a different directory.

The backend, front end, and test can use the same set of interface data sources, that is, after the interface is created, the back end is maintained on it, the front end uses him as the interface mock, and the test uses it to automate the interface. Data changes are synchronized to each end in real time, and there is no need to switch multiple software.

b. Supports importing interface data in more than 20 formats, such as postman,swagger, and realizes project migration at zero cost.

c. Support the export of swagger,html,word format interface documents, and do not kidnap users, you want to migrate to other systems is also generous to complete you.

With su