Front and rear end communication costs

As the development goes further, there are problems in the communication between the front and back end interfaces. Swagger is used as the interface debugging, but the parameters of the control layer and the return value swagger are not performing well. We still have to see the interface description in Javadoc, the parameter meaning and return value description, and the front-end response efficiency is too low. Debugging serves a dual purpose. In fact, Swagger provides interface documentation function, but back-end development does not explicitly require that swagger appropriate tag.

1 Interface Group

In Spring Boot, we define each interface to be organized with Controller as the first-level dimension, and the relationship between Controller and specific interface is one-to-many. We can define interfaces belonging to the same module in a Controller. By default, Swagger manages interfaces in groups by Controller. This grouping element is called a Tag in Swagger, but the Tag relationship to the interface is not one-to-many, it supports a richer many-to-many relationship.

1.1 Default Groups

First, let’s take a look at the data center example to see how Swagger, by default, organizes Tag interfaces based on Controller. Default Swagger interface

The default generated by Swagger is marked in the figureTagWith Spring in the BootControllerDisplay content and location.

1.2 Customizing the default group name

Next, we can try to customize the Tag with the @API annotation, like this:

After starting the application again, we see the following grouping in the code@ApiThe definition of thetagsContent replaces the tag name generated by default.

1.3 Merging Control Layer Interfaces

We now look at two control layers, which generate content:We will find that the two control layers, Water Resource Controller and Water Resource Property Controller, are actually in the field of Water Resource management. What the front end should see is a group of Water Resource interfaces, so the two control layers should be merged to the front end.

1.4 Fine-grained interface grouping

We should provide interfaces to the front end according to module grouping, so that the docking is more convenient. The front and back ends can communicate with each module as a unit, and there is no need to find interfaces needed by modules in each control layer. This is a merge down to an interface, such as grouping all (but not all) interfaces in the data center’s River List module. We can use the tags attribute in the @apiOperation annotation to make a more fine-grained definition of the interface class. For example, we can write requirements like this:

@RestController
@RequestMapping("/api/waterResource")
public class WaterResourceControler {

    @ApiOperation(value = "List of access water Resources Types", tags = "Rivers List")
    @GetMapping(value = "/type")
    public ResponseEntity getWaterResourceType() {
        return ResponseEntity.ok().body(waterResourceService.initTopTreeVMS());
    }

    @ApiOperation(value = "Get list of Secondary Water Levels", tags = "Rivers List")
    @GetMapping(value = "/level")
    public ResponseEntity getWaterResourceLevel() {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("waterResourceLevels", CommonEnum.RegionLevel.getLevels());
        return ResponseEntity.ok().body(jsonObject);
    }

    @ApiOperation(value = "Get water Tree List", tags = "Rivers List")
    @GetMapping(value = "/tree")
    public ResponseEntity getTreeVM(@RequestParam String type) {
        List<WaterResourceTreeVM> waterResourceTreeVMS = waterResourceService.getWaterResourceTreeVM(type);
        return newResponseEntity<>(waterResourceTreeVMS, HttpStatus.OK); }}Copy the code

The effect is shown below:

We should consciously provide interfaces to the front end according to the module. After forming a habit, the front and back ends communicate interfaces according to the module. In the future, when the module changes, the module interface will be adjusted uniformly. The same interface can belong to multiple modules, such as the river list interface. I’m sure you’ve noticedtagsThe property is actually an array type:

We can do this by defining multiple group names in a class using tags:

    @ApiOperation(value = "List of access water Resources Types", tags = {"Rivers List"."River data"})
    @GetMapping(value = "/type")
    public ResponseEntity getWaterResourceType() {
        return ResponseEntity.ok().body(waterResourceService.initTopTreeVMS());
    }
Copy the code

View the renderings:

3 RequestPart, requestParam, and MapAttribute

@RequestPart

    @PostMapping("/icons")
    @apiOperation (value = "new icon ")
    public ResponseEntity<IconDTO> createIcon(@RequestPart MultipartFile multipartFile, @RequestParam String name) {... }Copy the code

RequestPart the @requestPart annotation is used for submitting requests to multipart/form-data forms. The supported request method is MultipartFile, which belongs to Spring’s MultipartResolver class. This request is transmitted over the HTTP protocol. However, if there are other parameters in the parameter, continue to add the @requestParam annotation parameter. Java will not recognize it, but there is a way to convert a VM object to a normal @requestParam parameter using @mapAttribute:

    @PostMapping("/icons")
    @apiOperation (value = "New icon ", notes =" New icon, return IconDTO;" + "fileNoExistent Exception: A new icon file does not exist ")
    public ResponseEntity<IconDTO> createIcon(@RequestPart MultipartFile multipartFile, @ModelAttribute IconCreateVM iconCreateVM) {... }Copy the code

In this way, swagger can be distinguished, and the effect is as follows:

Click Try It Out! The request was sent successfully! To view request details:

.../api/icon/manage/icons?application=WATER_DISASTERS&classify=FLOOD&geoType=BUILD&name=abc&nameC=%E6%B5%8B%E8%AF%95
Copy the code

IconCreateVM was indeed split into the @requestParma parameter.