2021.2.24 更新

1 概述

Swagger主要用于生成API文档，本文演示了如何使用目前最新的OpenAPI3以及Swagger来进行接口文档的生成。

2 依赖

<dependency>

    <groupId>org.springdoc</groupId>

    <artifactId>springdoc-openapi-ui</artifactId>

    <version>1.4.7</version>

</dependency>

Gradle：

implementation( "org.springdoc:springdoc-openapi-ui:1.4.7")

3 配置

Swagger的配置很简单，仅需要一个@OpenAPIDefinition即可，@OpenAPIDefinition用于描述全局的配置信息，参考配置如下：

info表示基本信息，比如标题，版本，描述等
externalDocs是参考文档
servers是服务器地址

@OpenAPIDefinition(info = @Info(title = "标题",version = "版本",description = "描述"),

        externalDocs = @ExternalDocumentation(description = "参考文档",url = "https://www.baidu.com"),

        servers = @Server(url = "http://localhost:8080"))

public class SwaggerConfig {

}

接着在配置文件写上文档路径：

springdoc:

  api-docs:

    path: /doc

4 访问

运行后直接访问

localhost:8080/swagger-ui/index.html/

会出现如下界面：

搜索栏中输入配置文件中的路径/doc搜索即可：

或者直接访问：

http://localhost:8080/swagger-ui/index.html?url=/doc

5 控制器

下一步就是添加具体的接口，先来看一个简单的例子：

@RestController

@Tag(name = "测试Controller")

@RequestMapping("/")

public class TestController {

    @GetMapping("test")

    @Operation(description = "测试接口",tags = "测试Controller")

    public String test()

    {

        return "success";

    }

}

运行后可以看到多了一个接口，也就是@Tag与@Operation起作用了，注解说明如下：

@Tag表示标签，name指定标签的值，也可以加上description等属性
@Operation作用在方法上，可以指定描述以及标签，也可以指定参数以及返回值等信息

类似的注解还有很多，比如：

@Parameter：指定参数属性，比如description、name等
@ApiResponse：指定返回值，常用的属性有responseCode以及description
@Schema：用在实体类上以及实体类字段上，在接口上可以显示对应的值

6 完整示例

下面是一个接口控制器的完整示例：

@RestController

@Tag(name = "测试Controller")

@RequestMapping("/")

public class TestController {

    @GetMapping("test")

    @Operation(description = "测试接口",tags = {"测试Controller","测试"})

    public String test()

    {

        return "success";

    }

    @GetMapping("test2")

    @Operation(description = "这个也是测试接口",tags = {"测试Controller","2号测试接口"})

    @Parameter(description = "必要参数",name = "parm")

    public String test2(@RequestParam String parm)

    {

        return "需要参数";

    }

    @GetMapping("test3")

    @Operation(description = "带有返回状态的接口",tags = {"测试Controller"})

    @ApiResponse(responseCode = "111",description = "测试成功")

    @ApiResponse(responseCode = "222",description = "测试失败")

    public void test3(@RequestBody String body)

    {

    }

    @GetMapping("test4")

    @Operation(description = "User接口",tags = {"测试Controller"})

    @ApiResponse(responseCode = "100",description = "添加成功")

    public void test4(@RequestBody User user)

    {

    }

}

实体类：

@Getter

@Schema(description = "用户")

public class User {

    @Schema(description = "用户名")

    private String name;

    @Schema(description = "主键")

    private String id;

}

效果如图：