赵走x博客 - 开发者的网上家园

24、使用Swagger生成Web API文档

资源编号:551818 热度：143

24、使用Swagger生成Web API文档

高质量的API文档在系统开发的过程中非常重要。本节介绍什么是Swagger，如何在Spring Boot项目中集成Swagger构建RESTful API文档，以及为Swagger配置Token等通用参数。

# 一、什么是Swagger

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，是非常流行的API表达工具。

我们知道，RESTful API可能要面对多个开发人员或多个开发团队，涉及不同平台，包括iOS、Android或Web前端等。

为了降低与其他团队频繁沟通的成本，一般我们会创建一份统一的API说明文档来记录所有接口的使用说明。然而，普通的API文档存在以下问题：

- 1）由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），创建这样一份高质量的文档是一件非常烦琐的工作。
- 2）随着需求的不断变化，接口文档必须同步修改，就很容易出现文档和业务不一致的情况。

为了解决这些问题，Swagger应运而生，它能够自动生成完善的RESTful API文档，并根据后台代码的修改同步更新。

这样既可以减少维护接口文档的工作量，又能将说明内容集成到实现代码中，让维护文档和修改代码合为一体，实现代码逻辑与说明文档的同步更新。

另外，Swagger也提供了完整的测试页面来调试API，让API测试变得轻松、简单。

# 二、使用Swagger生成Web API文档在

Spring Boot项目中集成Swagger同样非常简单，只需在项目中引入springfox-swagger2和springfox-swagger-ui依赖即可。下面就以之前的用户管理模块接口为例来感受Swagger的魅力。

### 步骤01 配置Swagger的依赖。

```

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>
```

在上面的示例中，在项目pom.xml配置文件中引入了springfox-swagger2和springfox-swagger-ui两个依赖包。其中swagger2是主要的文档生成组件，swagger-ui为页面显示组件。

### 步骤02 创建Swagger2配置类。

```
@Configuration
@EnableSwagger2
public class Swagger2Config implements WebMvcConfigurer {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.weiz.example01.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("Spring Boot相关文章请关注：https://www.cnblogs.com/zhangweizhong")
                .termsOfServiceUrl("https://www.cnblogs.com/zhangweizhong")
                .contact("架构师精进")
                .version("1.0")
                .build();
    }
    /**
     *  swagger增加url映射
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}
```

在上面的示例中，我们在SwaggerConfig的类上添加了@Configuration和@EnableSwagger2两个注解。

@Configuration注解让Spring Boot来加载该类配置。

@EnableSwagger2注解启用Swagger2，通过配置一个Docket Bean，来配置映射路径和要扫描的接口所在的位置。

apiInfo主要配置Swagger2文档网站的信息，比如网站的标题、网站的描述、使用的协议等。

需要注意的是：
1）basePackage可以在SwaggerConfig中配置com.weiz.example01.controller，也可以在启动器ComponentScan中配置。
2）需要在SwaggerConfig中配置Swagger的URL映射地址：/swagger-ui.html。

### 步骤03 添加文档说明内容。

上面的配置完成之后，接下来需要在API上增加内容说明。

我们直接在之前的用户管理模块的UserController中增加相应的接口内容说明，代码如下：

```
@Api(tags = {"用户接口"})
@RestController
public class UserController {

@ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @PostMapping(value = "user")
    public JSONResult save(@RequestBody User user){
        System.out.println("用户创建成功："+user.getName());
        return JSONResult.ok(201,"用户创建成功");
    }

@ApiOperation(value="更新用户详细信息", notes="根据id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    @PutMapping(value = "user")
    public JSONResult update(@RequestBody User user) {
        System.out.println("用户修改成功："+user.getName());
        return JSONResult.ok(203,"用户修改成功");
    }

@ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
    @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "Long", paramType = "query")
    @DeleteMapping("user/{userId}")
    public JSONResult delete(@PathVariable String userId) {
        System.out.println("用户删除成功："+userId);
        return JSONResult.ok(204,"用户删除成功");
    }

@ApiOperation(value="查询用户",notes = "通过用户ID获取用户信息")
    @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "Long", paramType = "query")
    @GetMapping("user/{userId}")
    public JSONResult queryUserById(@PathVariable String userId) {
        User user =new User();
        user.setUserId(userId);
        user.setName("weiz");
        user.setAge(20);
        System.out.println("获取用户成功："+userId);
        return JSONResult.ok(200,"获取用户成功",user);
    }
}
```

在上面的示例中，主要为UserController中的接口增加了接口信息描述，包括接口的用途、请求参数说明等。
- 1）@Api注解：用来给整个控制器（Controller）增加说明。
- 2）@ApiOperation注解：用来给各个API方法增加说明。
- 3）@ApiImplicitParams、@ApiImplicitParam注解：用来给参数增加说明。

### 步骤04 查看生成的API文档。

完成上面的配置和代码修改之后，Swagger 2就集成到Spring Boot项目中了。接下来启动项目，在浏览器中访问http://localhost:8080/swagger-ui.html ，Swagger会自动构建接口说明文档，如图6-4所示。

![](http://oldmark.oss-cn-beijing.aliyuncs.com/2023/10/19/7b652b1c-6e56-11ee-86a8-0242ac1b0002/2e8f19a1089a488eba5a361c1497c169.png)

Swagger自动将用户管理模块的全部接口信息展现出来，包括接口功能说明、调用方式、请求参数、返回数据结构等信息。

在Swagger页面上，我们发现每个接口描述右侧都有一个按钮try it out，单击try it out按钮即可调用该接口进行测试。如图6-5所示，在获取人员信息的接口上单击try it out按钮，输入userId的请求参数“2001”，单击Execute按钮就会将请求发送到后台，从而进行接口验证测试。

![](http://oldmark.oss-cn-beijing.aliyuncs.com/2023/10/19/8ee5d1f0-6e56-11ee-820a-0242ac1b0002/0b56742a26754cef83fd8557a6c1741f.png)

# 三、为Swagger添加token参数

很多时候，客户端在调用API时需要在HTTP的请求头携带通用参数，比如权限验证的token参数等。

但是Swagger是怎么描述此类参数的呢？

接下来通过示例演示如何为Swagger添加固定的请求参数。

其实非常简单，修改Swagger2Config配置类，利用ParameterBuilder构成请求参数。具体示例代码如下：

```
@@Configuration
@EnableSwagger2
public class Swagger2Config implements WebMvcConfigurer {
    @Bean
    public Docket createRestApi() {
                // 添加请求参数，这里把token作为请求头参数传入后端
                ParameterBuilder parameterBuilder = new ParameterBuilder();
                List<Parameter> parameters = new ArrayList<Parameter>();
                parameterBuilder.name("token").description("token令牌")
                                .modelRef(new ModelRef("string")).parameterType("header").required(false).build();
                parameters.add(parameterBuilder.build());

return new Docket(DocumentationType.SWAGGER_2)
                                .apiInfo(apiInfo())
                                .select()

.apis(RequestHandlerSelectors.basePackage("com.weiz.example01.controller"))
                                .paths(PathSelectors.any())
                                .build()
                                .globalOperationParameters(parameters);
    }

…
}
```
在上面的示例中，通过ParameterBuilder类把token作为全局统一的参数添加到HTTP的请求头中。系统所有的API都会统一加上此参数。完成之后重新启动应用，再次查看接口，如图6-6所示，我们可以看到接口参数中已经支持发送token请求参数。

![](http://oldmark.oss-cn-beijing.aliyuncs.com/2023/10/19/da37ca3c-6e56-11ee-bbb5-0242ac1b0002/38b8dd60b84241ea81781f0f33d48fae.png)

人员管理模块中的所有API都统一加上了token参数，调用时Swagger会将token参数自动加入HTTP的请求头。

# 四、Swagger常用注解

Swagger提供了一系列注解来描述接口信息，包括接口说明、请求方法、请求参数、返回信息等，常用注解如表6-5所示。

![](http://oldmark.oss-cn-beijing.aliyuncs.com/2023/10/19/f156c740-6e56-11ee-8a56-0242ac1b0002/4ffd10c67cd343f0820679d719f34aa5.png)

在实际项目中，Swagger除了提供@ApiImplicitParams注解描述简单的参数之外，还提供了用于对象参数的@ApiModel和@ApiModelProperty两个注解，用于封装的对象作为传入参数或返回数据。

@ApiModel负责描述对象的信息

@ApiModelProperty负责描述对象中属性的相关内容

以上是在项目中常用的一些注解，利用这些注解就可以构建出清晰的API文档。