Swagger3.X 接口文档 (二)

一、Swagger3.x对象注解ApiModel讲解

APiModel和ApiModelProperty对象注解介绍

@ApiModel()

用于类表示对类进行说明，用于参数用实体类接收，value–表示对象名，description–描述

这种一般用在post创建的时候，使用对象提交这样的场景

@ApiModelProperty()

用于方法，字段； 表示对model属性的说明或者数据操作更改

value–字段说明

name–重写属性名字

dataType–重写属性类型

required–是否必填

example–举例说明

hidden–隐藏

@ApiModel(value = "新增用户请求模型")
@Data  //lombok(必须要写)
public class SaveUserRequest {

    @ApiModelProperty(value = "主键id")
    private int id;

    @ApiModelProperty(value = "名称" ,required = true,example = "mike")
    private  String name;

    @ApiModelProperty(value = "邮箱" ,required = true,example = "126.com")
    private String email;

    private String phone;

}

新增用户对象接口测试

    @ApiOperation("新增用户")
    @PostMapping("save")
    public JsonData  save(SaveUserRequest saveUserRequest) {  //参数SaveUserRequest
        //返回数据
        return JsonData.buildSuccess();
    }

import org.springframework.web.bind.annotation.*;
   @ApiOperation("新增用户")
    @PostMapping("save")
    public JsonData  save(@RequestBody SaveUserRequest saveUserRequest) {  //参数SaveUserRequest
        //返回数据
        return JsonData.buildSuccess();
    }

 

 

二、Swagger3.x响应结果ApiResponse和测试面板

@ApiResponse 描述接口响应

http://localhost:8081/swagger-ui/index.html/

import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@ApiOperation("用户登录")
@PostMapping("login")
@ApiResponses({
       @ApiResponse(responseCode = "302",description = "重定向"),
       @ApiResponse(responseCode = "403",description = "没权限"),
})
public JsonData login(
        @ApiParam(name = "name", value = "用户名", example = "mike") @RequestParam("name") String name,
        @ApiParam(name = "phone", value = "手机号", example = "110") @RequestParam("phone") String phone
        ) {
    //返回数据
    return JsonData.buildSuccess();
}

 使用常量

 

测试面板

Try it out|Execute|Response body

 

三、Swagger3.x和项目整合的注意事项

1）明确接口的Http请求方式：一个接口使用@RequestMapping会生成多个文档

2）线上不要开启接口文档 （修改：swagger.enable=false）

3）考虑团队当下和未来是否可以一直用，没有说百分百好用，缺点和优点都要知道。