使用Swagger生成Web API文档

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

1.什么是Swagger

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

普通的API文档存在以下问题：

1）由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），创建这样一份高质量的文档是一件非常烦琐的工作。

2）随着需求的不断变化，接口文档必须同步修改，就很容易出现文档和业务不一致的情况。为了解决这些问题，Swagger应运而生，它能够自动生成完善的RESTful API文档，并根据后台代码的修改同步更新。这样既可以减少维护接口文档的工作量，又能将说明内容集成到实现代码中，让维护文档和修改代码合为一体，实现代码逻辑与说明文档的同步更新。另外，Swagger也提供了完整的测试页面来调试API，让API测试变得轻松、简单。

2.使用Swagger生成Web API文档

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

步骤01 配置Swagger的依赖。

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

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

步骤02 创建Swagger2配置类。

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
    @Bean
    public Docket createRestApi () {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring boot中使用Swagger2构建RESTful APIs")
                .description("相关文章请关注:https://blog.csdn.net/weixin_45627039?spm=1000.2115.3001.5343")
                .termsOfServiceUrl("https://blog.csdn.net/weixin_45627039?spm=1000.2115.3001.5343")
                // .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,"用户删除成功");
            }
    }

在上面的示例中，主要为UserController中的接口增加了接口信息描述，包括接口的用途、请求参数说明等。

1）@Api注解：用来给整个控制器（Controller）增加说明。

2）@ApiOperation注解：用来给各个API方法增加说明。

3）@ApiImplicitParams、@ApiImplicitParam注解：用来给参数增加说明。

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

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

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

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

3.为Swagger添加token参数

很多时候，客户端在调用API时需要在HTTP的请求头携带通用参数，比如权限验证的token参数等。但是Swagger是怎么描述此类参数的呢？接下来通过示例演示如何为Swagger添加固定的请求参数。

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

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
    @Bean
    public Docket createRestApi() {
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        List<Parameter> parameters = new ArrayList<Parameter>();
        parameterBuilder.name("token").description("token令牌")
                .modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(parameters);
    }
    ...
}

在上面的示例中，通过ParameterBuilder类把token作为全局统一的参数添加到HTTP的请求头中。系统所有的API都会统一加上此参数。

完成之后重新启动应用，再次查看接口，如图所示，我们可以看到接口参数中已经支持发送token请求参数。

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

4.Swagger常用注解

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

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

@ApiModel负责描述对象的信息

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

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