SpringBoot - Swagger2的集成与使用教程（生成API接口文档）

SpringBoot - Swagger2的集成与使用教程（生成API接口文档）

 

    在前后端分离开发中，为了减少与其它团队的沟通成本，一般都会构建一份 RESTful API 文档来描述所有的接口信息。但传统的方式有许多弊端，不仅编写文档工作量巨大，而且维护不方便，测试也不方便（需要借助第三方工具，如 Postman 来测试）

    为解决这些问题，我们可以使用 Swagger 2 来构建在线接口文档，下面通过样例进行演示。

 

一、基本介绍

1，什么是 Swagger 2

    Swagger 2 是一个开源软件框架，可以帮助开发人员设计、构建、记录和使用 RESTful Web 服务，它将代码和文档融为一体，可以完美解决文档编写繁琐、维护不方便等问题。使得开发人员可以将大部分精力集中到业务中，而不是繁杂琐碎的文档中。

 

2，安装配置

（1）首先编辑项目的 pom.xml 文件，添加 Swagger 2 相关依赖： 

注意：因为我这里引入的 swagger ui 是 2.7 以上的版本，所以还需要引入 guava，否则会因为 guava 兼容性问题造成项目启动报错（无法启动）

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

<dependency>     <groupId>io.springfox</groupId>     <artifactId>springfox-swagger2</artifactId>     <version>2.9.2</version> </dependency> <dependency>     <groupId>io.springfox</groupId>     <artifactId>springfox-swagger-ui</artifactId>     <version>2.9.2</version> </dependency> <dependency>     <groupId>com.google.guava</groupId>     <artifactId>guava</artifactId>     <version>20.0</version> </dependency>

（2）接着创建 Swagger 2 的配置类，代码如下： 代码说明：

• 首先通过 @EnableSwagger2 注解开启了 Swagger 2，然后最主要的是配置一个 Docket。
• 通过 apis 方法配置要扫描的 controller 位置，通过 paths 方法配置路径。
• 在 apiInfo 中构建文档的基本信息，例如描述、联系人信息、版本、标题等。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

@Configuration @EnableSwagger2 public class SwaggerConfig {     @Bean     Docket docket() {         return new Docket(DocumentationType.SWAGGER_2)                 .apiInfo(apiInfo())                 .select()                 .apis(RequestHandlerSelectors.basePackage("com.example.demo"))                 .paths(PathSelectors.any())                 .build();     }       private ApiInfo apiInfo() {         return new ApiInfoBuilder()                 .title("API测试文档")                 .description("DEMO项目的接口测试文档")                 .termsOfServiceUrl("http://www.hangge.com")                 .version("1.0")                 .contact(new Contact("航歌",                         "http://www.hangge.com",                         "hangge@hangge.com"))                 .build();     } }

 

二、使用样例

1，添加注解

（1）首先我们在 Controller 上添加相关的 @Api 注解：

（1）@Api 注解标注在类上用来描述整个 Controller 信息。
（2）@ApiOperation 注解标注在方法上，用来描述一个方法的基本信息。
（3）@ApiImplicitParam 注解标注在方法上，用来描述方法的参数。其中 paramType 是指方法参数的类型，有如下可选值：

• path：参数获取方式为 @PathVariable
• query：参数获取方式为 @RequestParam
• header：参数获取方式为 @RequestHeader
• body
• form

（4）如果有多个参数，可以将多个参数的 @ApiImplicitParam 注解放到 @ApiImplicitParams 中。
（5）@ApiResponse 是对响应结果的描述。code 表示响应码，message 为相应的描述信息。如果有多个 @ApiResponse，则放在一个 @ApiResponses 中。
（6）@ApiIgnore 注解表示不对某个接口生成文档。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44

@RestController @Api(tags = "用户数据接口") public class UserController {     @ApiOperation(value ="查询用户", notes = "根据 id 查询用户")     @ApiImplicitParam(paramType = "path", name = "id", value = "用户 id", required = true)     @GetMapping("/user/{id}")     public String getUserById(@PathVariable Integer id){         return "查找的用户id是：" + id;     }       @ApiOperation(value = "新增用户", notes = "根据传入的用户名和密码添加一个新用户")     @ApiImplicitParams({             @ApiImplicitParam(paramType = "query", name = "username",                     value = "用户名", required = true, defaultValue = "test"),             @ApiImplicitParam(paramType = "query", name = "password",                     value = "密码", required = true, defaultValue = "123")     })     @PostMapping("/user")     public String addUser(@RequestParam String username, @RequestParam String password) {         return "新增用户：" + username + " " + password;     }       @ApiOperation(value = "删除用户", notes = "根据 id 删除用户")     @ApiResponses({             @ApiResponse(code = 200, message = "删除成功！"),             @ApiResponse(code = 500, message = "删除失败！")     })     @DeleteMapping("/user/{id}")     public Integer deleteUserById(@PathVariable Integer id) {         return id;     }       @ApiOperation(value = "修改用户", notes = "传入用户信息进行更新修改")     @PutMapping("/user")     public String updateUser(@RequestBody User user){         return user.toString();     }       @ApiIgnore     @GetMapping("/user/test")     public String test() {         return "这是一个测试接口，不需要在api文档中显示。";     } }

（2）接着对模型对象也添加相关的注解：

    由于在上面 Controller 里的 updateUser 方法中，使用 @RequestBody 注解来接收数据，此时可以通过 @ApiModel 注解和 @ApiModelProperty 注解配置 User 对象的描述信息。

1 2 3 4 5 6 7 8 9 10 11 12 13 14

@Getter @Setter @ToString @ApiModel(value = "用户实体类", description = "用户信息描述类") public class User {     @ApiModelProperty(value = "用户id")     private Integer id;       @ApiModelProperty(value = "用户名")     private String username;       @ApiModelProperty(value = "用户密码")     private String password; }

 

2，查看接口文档

（1）启动 Spring Boot 项目，在浏览器中输入 http://localhost:8080/swagger-ui.html 即可看到接口文档。

 

（2）展开任意一个接口描述，单击 Try it out 按钮后，可以实现对该接口的测试。

 

附：使用 swagger-bootstrap-ui 代替原来的 ui

（1）如果觉得原先使用的 swagger ui 比较丑、或者不方便的话，可以试试 swagger-bootstrap-ui。只需修改 pom.xml 文件，将原来的 springfox-swagger-ui 依赖替换成  swagger-bootstrap-ui 即可。

注意：1.9.6 是 swagger-bootstrap-ui 的最后一个版本。由于各种原因，原作者又另起一新的项目：knife4j-spring-ui。knife4j 会包含 swagger-bootstrap-ui 的所有特性，并增加许多新特性，有兴趣的小伙伴可以尝试一下。

 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

<dependency>     <groupId>io.springfox</groupId>     <artifactId>springfox-swagger2</artifactId>     <version>2.9.2</version> </dependency> <dependency>     <groupId>com.github.xiaoymin</groupId>     <artifactId>swagger-bootstrap-ui</artifactId>     <version>1.9.6</version> </dependency> <dependency>     <groupId>com.google.guava</groupId>     <artifactId>guava</artifactId>     <version>20.0</version> </dependency>

（2）项目启动后，通过 http://localhost:8080/doc.html 地址即可访问新的 UI 界面：

 

（3）可以看到 bootstrap 风格的界面样式比原先的清爽、高效许多：