Small knowledge, big challenge! This article is participating in the creation activity of “Essential Tips for Programmers”.

With the popularity of the separation of the front and back ends, it is very common to quarrel with the front and back end personnel in daily code. Therefore, the blogger formulated a series of interface document compilation specifications in the process of the company’s interface and interface document compilation. Make the interface search more clear, more standardized input and output parameters. This will greatly reduce the communication time between the front and back end personnel.

Code specification

  1. Write the interface of the same business in a class and specify the business name, as shown in Figure 2.

  1. Describe the interface in detail and specify the request type. Don’t use RequestMapping, as shown in Figure 2.

Some of you have asked, according to restful rules, interface path should only be a noun, you are not professional. Because the company of the blogger is small and the quality of the staff is relatively ordinary, so in order to avoid some accidents in the development, so it is not used here.

  1. Write the description of the input and output parameters, and the input parameter must be of object type. The output parameter is also an object type. Basic type entry and exit parameters are strictly prohibited, as shown in Figure 2.

  1. Create different VO return objects to prevent return value contamination.

Avoid a VO object that all interfaces use and returns a bunch of useless fields.

2. Export swagger to word

After writing Swagger, word may be required for archiving or for detailed design. If rewriting is a very second thing. Open source projects are recommended. The idea is to access the interface provided by Swagger to retrieve document data and render it into a Word file.

1. Download the project

Project address: github.com/JMCuixy/swa…

2. Modify the configuration

This specifies the port from which you want to export the project./v2/api-docsProvides data interface for Swagger.

3. Export the document

Run the project, pleasehttp://127.0.0.1:8080/swagger-ui.html(Open source project path). Here he provides several interfaces, as shown below.Here we choose:One-click download of swagger document as DOC document“, then click Try It Out and click Download to complete the download.