SpringBoot 集成 Swagger 快速实现项目接口文档

Swagger 是一款目前世界最流行的API管理工具

官网

World’s Most Popular API Framework | Swagger
Swagger Annotation

集成步骤

在项目 pom 中引入以下依赖。

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.7.0version>
dependency>
<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.7.0version>
dependency>

在项目中对 Swagger 进行简单配置。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				.apis(RequestHandlerSelectors.any())
				.paths(or(regex("/api/.*"))).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("轻实训-移动端 API").version("1.0").build();
    }
}

启动项目后，在项目的根请求后加上 swagger-ui.html 即可访问。

常用注解描述

控制层相关注解

在控制层上使用 @Api(tags = "用户登录") 可以指定请求的名称。

@RestController
@Api(tags = "用户登录")
@RequestMapping("/api/login")
public class LoginController { ... }

在控制层的方法上使用 @ApiOperation("触发登录") 可以指定具体请求的名称。

@PostMapping("")
@ApiOperation("触发登录")
public ResponseData login(@RequestBody LoginVO login) { ... }

上述代码的整体效果如下图。

实体类相关注解

在实体类上使用 @ApiModel("用户登录") 可以指定具体请求需要的参数对象名称。

@ApiModel("用户登录")
public class LoginVO { ... }

在实体类的字段上使用 @ApiModelProperty("登录名") 可以指定参数对象的字段名称。

@ApiModelProperty("登录名")
private String loginName;

上述代码的整体效果如下图。

在请求方法上标注非形参的参数

如果有些参数是在方法中通过 request.getParameter() 来获取，Swagger 默认就无法将这种类型的参数显示在参数列表中，需要在控制层的方法上使用 @ApiImplicitParams() 来标注这些参数。

@PostMapping("/page")
@ApiOperation("分页数据")
@ApiImplicitParams({
  @ApiImplicitParam(name = "projectName", value = "项目名称", paramType = "query", dataType = "String")
})
public ResponseData page(int page, int size) {
    return super.page(page, size);
}

上述代码的整体效果如下。

配置 Swagger 的实际请求路径

在 Swagger 中，打开具体的请求后，可以在最下方点击 Try it out! 对接口进行快速测试。发起请求的根路径默认和当前网址的根路径保持一致。

例如，当前打开 Swagger 的网址是 http://localhost:8080/mis/swagger-ui.html ，那么发起登录请求的链接就是 http://localhost:8080/mis/api/login 。如果实际发起请求的根路径不是当前网址的根路径，可以通过以下方式修改。

springfox:
  documentation:
    swagger:
      v2:
        host: asing1elife.com

在配置文件中添加以上代码后，发起登录请求的链接就会变为 http://asing1elife.com/mis/api/login 。