2021.2.24 更新
1 概述
Swagger主要用于生成API文档，本文演示了如何使用目前最新的OpenAPI3以及Swagger来进行接口文档的生成。
2 依赖
1<dependency> 2 <groupId>org.springdoc</groupId> 3 <artifactId>springdoc-openapi-ui</artifactId> 4 <version>1.4.7</version> 5</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 { }
接着在配置文件写上文档路径：
1springdoc: 2 api-docs: 3 path: /doc
4 访问
运行后直接访问
localhost:8080/swagger-ui/index.html/
会出现如下界面：
搜索栏中输入配置文件中的路径/doc搜索即可：
或者直接访问：
http://localhost:8080/swagger-ui/index.html?url=/doc
5 控制器
下一步就是添加具体的接口，先来看一个简单的例子：
1@RestController 2@Tag(name = "测试Controller") 3@RequestMapping("/") 4public class TestController { 5 @GetMapping("test") 6 @Operation(description = "测试接口",tags = "测试Controller") 7 public String test() 8 { 9 return "success"; 10 } 11}
运行后可以看到多了一个接口，也就是@Tag与@Operation起作用了，注解说明如下：
@Tag表示标签，name指定标签的值，也可以加上description等属性@Operation作用在方法上，可以指定描述以及标签，也可以指定参数以及返回值等信息
类似的注解还有很多，比如：
@Parameter：指定参数属性，比如description、name等@ApiResponse：指定返回值，常用的属性有responseCode以及description@Schema：用在实体类上以及实体类字段上，在接口上可以显示对应的值
6 完整示例
下面是一个接口控制器的完整示例：
1@RestController 2@Tag(name = "测试Controller") 3@RequestMapping("/") 4public class TestController { 5 @GetMapping("test") 6 @Operation(description = "测试接口",tags = {"测试Controller","测试"}) 7 public String test() 8 { 9 return "success"; 10 } 11 12 @GetMapping("test2") 13 @Operation(description = "这个也是测试接口",tags = {"测试Controller","2号测试接口"}) 14 @Parameter(description = "必要参数",name = "parm") 15 public String test2(@RequestParam String parm) 16 { 17 return "需要参数"; 18 } 19 20 @GetMapping("test3") 21 @Operation(description = "带有返回状态的接口",tags = {"测试Controller"}) 22 @ApiResponse(responseCode = "111",description = "测试成功") 23 @ApiResponse(responseCode = "222",description = "测试失败") 24 public void test3(@RequestBody String body) 25 { 26 } 27 28 @GetMapping("test4") 29 @Operation(description = "User接口",tags = {"测试Controller"}) 30 @ApiResponse(responseCode = "100",description = "添加成功") 31 public void test4(@RequestBody User user) 32 { 33 } 34}
实体类：
1@Getter 2@Schema(description = "用户") 3public class User { 4 @Schema(description = "用户名") 5 private String name; 6 @Schema(description = "主键") 7 private String id; 8}
效果如图：
7 参考源码
Java版：
Kotlin版：