Spring Boot整合Swagger 2

Spring Boot整合Swagger 2

1. Swagger 2简介

在前后端分离开发中，为了减少与其他团队的沟通成本，-般构建一份RESTful API文档来描述所有的接口信息，但是这种做法有很大的弊端，分别说明如下:

• 接口众多，编写RESTful API文档工作量巨大，因为RESTful API文档不仅要包含接口的基本信息，如接口地址、接口请求参数以及接口返回值等，还要包含HTTP请求类型、HTTP请求头、请求参数类型、返回值类型、所需权限等。
• 维护不方便， 一旦接口发生变化，就要修改文档。
• 接口测试不方便， 一般只能借助第三方工具(如Postman)来测试。

Swagger2是一个开源软件框架，可以帮助开发人员设计、构建、记录和使用RESTful Web服务，它将代码和文档融为一-体，可以完美解决上面描述的问题，使开发人员将大部分精力集中到业务中，而不是繁杂琐碎的文档中。

Swagger2可以非常轻松地整合到Spring Boot项目中，下 面来看如何整合。

2. 整合Spring Boot

首先创建Spring Boot Web项目，添加Swagger 2相关依赖，代码如下:

    io.springfox
    springfox-boot-starter
    3.0.0


    io.swagger
    swagger-annotations
    1.5.22


    io.swagger
    swagger-models
    1.5.22

注意：因为我这里引入的 swagger ui 是 2.7 以上的版本，所以还需要引入 guava，否则会因为 guava 兼容性问题造成项目启动报错（无法启动）。SpringBoot 版本 2.2.6.RELEASE，版本不能高与这个版本，否则 Swagger 版本不匹配报错。

接下来创建Swagger 2的配置类，代码如下:

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                //.enable(false)
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("suohechuan.testforever"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot中使用Swagger2接口规范")
                //文档描述
                .description("接口说明")
                //服务条款URL
                .termsOfServiceUrl("http://localhost:8080/")
                //版本号
                .version("1.0.0")
                .build();
    }
}

代码解释:

• 通过apis方法配置要扫描的controller位置，通过paths方法配置路径。

• 在apiInfo中构建文档的基本信息，例如描述、联系人信息、版本、标题等。

使用@EnableOpenApi注解，启用swagger配置

@EnableOpenApi
@SpringBootApplication
public class TestforeverApplication {
    public static void main(String[] args) {
        SpringApplication.run(TestforeverApplication.class, args);
    }
}

Swagger 2配置完成后，接下来就可以开发接口了，代码如下:

@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文档中显示。";
    }
}

代码解释:

• @Api注解用在类上，用来描述整个Controller信息。
• @ApiOperation 注解用在开发方法上，用来描述一个方法的基本信息，value 是对方法作用的一个简短描述，notes则用来备注该方法的详细作用。
• @ApiImplicitParam注解用在方法上,用来描述方法的参数, paramType是指方法参数的类型,可选值有path (参数获取方式@PathVariable )、query (参数获取方式@RequestParam ). header(参数获取方式@RequestHeader)、body 以及form; name 表示参数名称，和参数变量对应;value是参数的描述信息; required 表示该字段是否必填; defaultValue 表示该字段的默认值。注意，这里的required和defaultValue等字段只是文档上的约束描述，并不能真正约束接口，约束接口还需要在@RequestParam中添加相关属性。
  如果方法有多个参数,可以将多个参数的@ApilmplicitParam注解放到@ApiImplicitParams中。
• @ApiResponse 注解是对响应结果的描述，code 表示响应码，message 表示相应的描述信息,若有多个@ApiResponse,则放在一个@ApiResponses中。
• 在 updateUser方法中，使用@RequestBody注解来接收数据，此时可以通过@ApiModel注解和@ApiModelProperty注解配置User对象的描述信息。
• @ApiIgnore 注解表示不对某个接口生成文档。

（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 注解表示不对某个接口生成文档。

接下来启动Spring Boot 项目，在浏览器中输入启动 Spring Boot 项目，在浏览器中输入 http://localhost:8080/swagger-ui/index.html 即可看到接口文档。即可看到接口文档，如图所示。