Api 接口文档生成工具 Swagger 的使用

Swagger 简介

前后端分离的架构中，往往需要构建接口文档。而接口文档中需要定义各种各样的参数，单独写起来比较繁琐，尤其是当接口十分多时，效率十分低下。同时，传统的接口维护十分不方便，一旦接口发生变换，文档就必须跟着修改。除此之外，接口测试往往需要通过第三方工具（如 Postman）进行。Swagger 的诞生就是为了解决上述种种问题。

Swagger 作为一款优秀的 Api 接口文档生成工具，主要提供如下两个功能：

• 接口文档实时更新：只需在项目通过配置 + 注解即可快速生产接口文档，并且能够实时更新，可维护性强
• 可以在线测试接口：提供在线测试功能，无需使用第三方软件进行接口测试

1、创建项目

创建一个 Spring Boot 项目，如果官网进不去，可以采用如下地址：https://start.aliyun.com/ 创建

下一步

添加 web 依赖

Finish 完成

2、导入 Swagger 依赖

在 pom.xml 中，添加如下依赖：

        <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>

3、配置 Swagger

创建一个名为 SwaggerConfig 的类，并在类名上方添加 @Configuration 以及 @EnableSwagger2 注解

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(Environment environment) {
//        Profiles profiles = Profiles.of("dev", "test");
//        boolean b = environment.acceptsProfiles(profiles);
//        可在下方添加 .enbale(b)，这样就可以实现根据配置环境决定是否开启 Swagger 访问
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.study.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .description("小白接口测试文档")
                        .contact(new Contact("努力学习","authorURL","authorEmail"))
                        .version("v1.0")
                        .title("API 测试文档")
                        .license("Apache2.0")
                        .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                        .build());
    }

}

• apis 中定义的 backPackage 为需要扫描的包，指定为 controller 所在的包即可
• apiInfo 中的各个参数对应文档的相关描述信息、如标题、作者、版本、描述等

注释部分解释：

通过 Environment 参数可以获取当前的环境，如果配置环境为 Profiles.of("dev", "test") 中参数定义的，则传入 enable 的值为 true，否则为 false，只有当 enable 的值为 true 时才能访问 Swagger 文档，当我们正式上线项目时需要关闭接口文档，即上线的环境对应的配置文件名不要出现在 Profiles.of() 中的参数中，这样得到的 boolean 变量 b 的值就 false，Swager 文档将关闭

如果要创建组，可添加 groupName 参数，创建多个组则定义多个 Docket方法，在其中指定 groupName 即可。
先运行 Spring Boot 项目查看一下效果，在浏览器地址栏中输入 localhost:8080/swagger-ui.html

以后我们只要输入上面那个地址即可访问接口文档。

4、编写接口，添加注释

开启了 Swagger 之后，我们就可以在 Controller 中写接口了。

@RestController
@RequestMapping("/students")
@Api(tags = "学生数据接口")
public class StudentController {

    @GetMapping("/{id}")
    @ApiOperation(value = "查询学生", notes = "根据学号查询学生")
    @ApiImplicitParam(paramType = "path",name = "id",value = "学生学号",required = true)
    public RespBean getStudentById(@PathVariable("id") int id) {
        return new RespBean("success","查询学号为"+id+"的学生成功！");
    }

    @DeleteMapping("/{id}")
    @ApiResponses({
            @ApiResponse(code = 200, message = "删除成功！"),
            @ApiResponse(code = 500, message = "删除失败！")
    })
    @ApiOperation(value = "删除学生", notes = "通过学号删除学生")
    public RespBean deleteStudentById(@PathVariable("id") int id) {
        return new RespBean("success","删除学号为"+id+"的学生成功！");
    }

    @ApiOperation(value = "增加学生", notes = "传入姓名与密码，以添加学生")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "name", value = "学生姓名", required = true, defaultValue = "aaa"),
            @ApiImplicitParam(paramType = "query", name = "pwd", value = "学生密码", required = true, defaultValue = "123")
    })
    @PostMapping("/")
    public RespBean addStudent(@RequestParam("name") String name, @RequestParam("pwd") String pwd) {
        return new RespBean("success","增加了name为"+name+"的学生！");
    }

    @PutMapping("/")
    @ApiOperation(value = "更新学生", notes = "传入姓名与密码，以更新学生")
    public RespBean updateStudent(@RequestBody Student student) {
        return new RespBean("success","更新后的学生信息为："+student.toString());
    }

}

• @Api 注解使用在类上，用于描述该 Controller 的信息

• @ApiOperation 注解作用在方法上，用于描述该方法的信息

  参数	含义
  value	方法的简短描述
  notes	方法的详细说明

• @ApiImplicitParam 注解作用在方法上，用于描述方法的参数

  参数名称	含义
  paramType	参数类型
  name	参数名称
  value	参数描述信息
  required	是否必填
  defaultValue	默认值

• paramType 的相关取值如下：

  paramType	对应获取方式
  path	@PathVariable
  query	@RequestParam
  header	@RequestHeader

• @ApiResponse 注解描述方法的响应结果

  参数名称	含义
  code	响应码
  message	描述信息

• @ApiModel 可以给实体类添加描述信息；@ApiModelProperty 可以给实体类的属性添加描述信息

5、查看接口文档

再次启动 Spring Boot 项目，输入http://localhost:8080/swagger-ui.html，如下所示：

上图中显示了 Controller 中所有定义的接口

查看更新学生的接口描述信息，由于我们采用的是 @RequestBody 进行接收，可以看到其 content type 为 application/json

Models 中显示了实体类的描述信息

6、在线测试接口

点击右上方的 Try it out 即可进行在线测试，输入所需参数，然后点击 Execute 即可：

测试成功，结果如下：

以上就是 Spring Boot 项目中整合 Swagger 的步骤。其实步骤并不复杂。总的来说，Swagger 还是一款十分不错的工具。最后，在正式发布项目时，要记得关闭 Swagger ！