Swagger3常用用法及属性

前言

这里简单介绍 swagger3的常用用法，比如：

1. 注解的常用属性
2. 接口的常用注解及其配置
3. 注解的简要说明
4. 配置注解后的UI demo对比展示

配置 swagger-ui

1. 下载最新版swagger-ui
2. 启动后进入swagger-ui界面
3. 输入自己的地址：http://localhost:8083/v3/api-docs

注解常用属性

@Schema 标记实体和属性

@Schema(name = "demoDto", title = "前端请求的实体", description = "用于get请求和Post请求")
@Data
public class DemoDTO implements Serializable {
    @Schema(name = "name", title = "姓名", description = "传递姓名", required = true)
    private String name;
    @Schema(title = "年龄", description = "传递年龄", defaultValue = "0")
    private Integer age;
}

标记在类上时：

1. title：实体名称
2. description：实体描述

标记在属性上时：

1. name：属性名称
2. title：中文名称
3. description：描述
4. required：是否必须
5. defaultValue：默认值

@Tag、@Tags标记一个类型的操作

我们先了解一下类型注解的结构：

上图的 demo rest接口、demo常规接口就是 @Tag注解的效果。

这里 @Tag、@Tags 用在 类上或方法@Operation 注解中，@Tags就是 @Tag的一个集合。

主要配置

我们主要配置 @Tag 的两个属性：

1. name：当前类型名称
2. description：当前类型的描述

注意事项

1. name名称相同时，操作会合并。
2. name名称相同合并后，类或方法中的接口会视为同一操作类型

@Tags demo

@Tags(value = {
        @Tag(name = "demo rest接口", description = "演示接口描述：这是第一个REST DEMO"),
        @Tag(name = "demo-常规接口", description = "演示接口描述：这也是第二个REST DEMO")
})
@Slf4j
@RestController
@RequestMapping(value = "/demo-rest")
public class DemoRestController {
}

@Tag demo

@Tag(name = "demo常规接口", description = "演示接口描述：这是第一个DEMO")
@Slf4j
@Controller
@RequestMapping(value = "demo")
public class DemoController {
}

请求的几种情况

@Parameter注解在方法上 与 在@Operation.parameters中没有区别

GET请求@RequestParam 参数

@Tags(value = {
        @Tag(name = "demo rest接口", description = "演示接口描述：这是第一个REST DEMO"),
        @Tag(name = "demo常规接口", description = "演示接口描述：这也是第二个REST DEMO")
})
@Slf4j
@RestController
@RequestMapping(value = "/demo-rest")
public class DemoRestController {
    @Operation(summary = "get请求", description = "get des", method = "GET", parameters = {
            /*name 属性名，描述，必填，示例*/
            @Parameter(name = "id", description = "主键des", required = true, example = "1"),
            /*@RequestParam注解中的必填会默认带入进来*/
            @Parameter(name = "name", description = "名称", example = "maxzhao"),
            /*@RequestParam注解中的 defaultValue 会带入到 example中*/
            @Parameter(name = "age", description = "年龄", required = false)},
            /*tag会根据name分配到 对应的 @Tag中，如果没有对应的 @Tag 则会创建*/
            tags = {"额外的分组", "demo常规接口"})
    @GetMapping("/get1")
    /*响应集合的实体*/
    @ApiResponse(content = @Content(schema = @Schema(implementation = DemoVO.class)))
    public ResponseEntity<DemoVO> getMapping1(@RequestParam(value = "id") String id, @RequestParam(value = "name") String name,
            /*这里的 defaultValue 会被带入到 swagger3注解@Parameter的example中，在swagger文档中展示
             * 但是前端不传递age时，这里也会有默认值1，@Parameter.example 则不会*/
                                              @RequestParam(value = "age", required = false, defaultValue = "1") Integer age) {
        log.info("id=>{}", id);
        return ResponseEntity.ok(new DemoVO());
    }
}

swagger文档展示：

请求参数

响应

GET请求实体参数

@Tags(value = {@Tag(name = "demo rest接口", description = "演示接口描述：这是第一个REST DEMO"), @Tag(name = "demo常规接口", description = "演示接口描述：这也是第二个REST DEMO")})
@Slf4j
@RestController
@RequestMapping(value = "/demo-rest")
public class DemoRestController {
    @Operation(summary = "get请求", description = "实体接收参数",
            parameters = @Parameter(name = "demoDto",
                    content = @Content(schema = @Schema(implementation = DemoDTO.class))))
    @GetMapping("/get2")
    /*响应集合的实体*/
    @ApiResponse(content = @Content(array = @ArraySchema(schema = @Schema(implementation = DemoVO.class))))
    public ResponseEntity<List<DemoVO>> getMapping2(DemoDTO demoDto) {
        log.info("id=>{}", demoDto);
        return ResponseEntity.ok(new ArrayList<>());
    }
}

swagger 文档示例：

请求参数

响应

POST请求实体参数

@Tags(value = {@Tag(name = "demo rest接口", description = "演示接口描述：这是第一个REST DEMO"), @Tag(name = "demo常规接口", description = "演示接口描述：这也是第二个REST DEMO")})
@Slf4j
@RestController
@RequestMapping(value = "/demo-rest")
public class DemoRestController {
    @Operation(summary = "Post请求", description = "实体参数",
            /*请求体*/
            requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(required = true, description = "请求体",
                    content = @Content(schema = @Schema(implementation = DemoDTO.class))),
            /*响应集合的实体*/
            responses = @ApiResponse(content = @Content(array = @ArraySchema(schema = @Schema(implementation = DemoVO.class)))))
    @PostMapping("/post")
    public ResponseEntity<DemoVO> postMapping(@RequestBody DemoDTO demoDto) {
        log.info("id=>{}", demoDto);
        return ResponseEntity.ok(new DemoVO());
    }
}

swagger 文档示例：

请求参数

响应

本文地址： https://github.com/maxzhao-it/blog/post/9dffc2b8/