【一篇文章就够了】web文档神器——Swagger2

简介

Spring Boot 框架是目前非常流行的微服务框架，我们很多情况下使用它来提供 Rest API。而对于 Rest API 来说很重要的一部分内容就是文档，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，这一点对于保证 API 文档的及时性将有很大的帮助。本文将使用 Swagger 2 规范的 Springfox 实现来了展示如何在 Spring Boot 项目中使用 Swagger，主要包含了如何使用 Swagger 自动生成文档、使用 Swagger 文档以及 Swagger 相关的一些高级配置和注解。

---

链接：https://developer.ibm.com/zh/articles/j-using-swagger-in-a-spring-boot-project/
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。

Demo

第一步：创建一个SpringBoot项目
这就不多说了
第二步：导入依赖

<!--    swagger依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
<!--        swaggerUI-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

第三步：创建接口

如图所示创建Java文件

1. SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

@Configuration 是告诉 Spring Boot 需要加载这个配置类， @EnableSwagger2 是启用 Swagger2。

还可以配置一些信息

@Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfo(
                "Spring Boot 项目集成 Swagger 实例文档",
                "我的博客网站：https://itweknow.cn，欢迎大家访问。",
                "API V1.0",
                "Terms of service",
                new Contact("名字想好没", "https://itweknow.cn", "gancy.programmer@gmail.com"),
                "Apache", "http://www.apache.org/", Collections.emptyList());
    }

配置之后，UI界面就会如下图所示

2. UserController

@RestController
@RequestMapping("/user")
public class UserController {

    @PostMapping("/add")
    public boolean addUser(@RequestBody User user) {
        return false;
    }
    @GetMapping("/find/{id}")
    public User findById(@PathVariable("id") int id) {
        return new User();
    }
    @PutMapping("/update")
    public boolean update(@RequestBody User user) {
        return true;
    }

}

这个很简单，不多说
3. User
同样不多说

第四步：查看

方法一：运行项目，打开链接：http://localhost:8080/v2/api-docs。但是这样查看的是json文件，没啥用。
方法二：通过http://localhost:8080/swagger-ui.html，打开swagger的UI界面，如下图。

接口过滤

1. @ApiIgnore
   如果想在文档中屏蔽掉删除用户的接口（user/delete），那么只需要在删除用户的方法上加上 @ApiIgnore 即可。

@ApiIgnore
public boolean delete(@PathVariable("id") int id)

2. 在 Docket 上增加筛选。Docket 类提供了 apis() 和 paths() 两个方法来帮助我们在不同级别上过滤接口：

apis() ：这种方式我们可以通过指定包名的方式，让 Swagger 只去某些包下面扫描。
paths() ：这种方式可以通过筛选 API 的 url 来进行过滤。
在集成 Swagger2 的章节中我们这两个方法指定的都是扫描所有，没有指定任何过滤条件。如果我们在我们修改之前定义的 Docket 对象的 apis() 方法和 paths() 方法为下面的内容，那么接口文档将只会展示 /user/add 和 /user/find/{id} 两个接口。

.apis(RequestHandlerSelectors.basePackage("cn.itweknow.sbswagger.controller"))
.paths(Predicates.or(PathSelectors.ant("/user/add"),
        PathSelectors.ant("/user/find/*")))

自定义响应消息

Swagger 允许我们通过 Docket 的 globalResponseMessage() 方法全局覆盖 HTTP 方法的响应消息，但是首先我们得通过 Docket 的 useDefaultResponseMessages 方法告诉 Swagger 不使用默认的 HTTP 响应消息，假设我们现在需要覆盖所有 GET 方法的 500 和 403 错误的响应消息，我们只需要在 SwaggerConfig.java 类中的 Docket Bean 下添加如下内容：

.useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.GET, new ArrayList() {{
                    add(new ResponseMessageBuilder()
                            .code(500)
                            .message("服务器发生异常")
                            .responseModel(new ModelRef("Error"))
                            .build());
                    add(new ResponseMessageBuilder()
                            .code(403)
                            .message("资源不可用")
                            .build());
                }});

添加如上面的代码后，如下图所示，您会发现在 SwaggerUI 页面展示的所有 GET 类型请求的 403 以及 500 错误的响应消息都变成了我们自定义的内容。

Swagger UI 的使用

1.接口查看

SwaggerUI 会以列表的方式展示所有扫描到的接口，初始状态是收缩的，我们只需要点击展开就好，而且会在左边标识接口的请求方式（GET、POST、PUT、DELETE 等等）。

2.接口调用

如下图所示，点击接口展开后页面右上角的 Try it out 按钮后，页面会变成如图所示：

SwaggerUI 会给我们自动填充请求参数的数据结构，我们需要做的只是点击 Execute 即可发起调用

3.Model

如下图所示，SwaggerUI 会通过我们在实体上使用的 @ApiModel 注解以及 @ApiModelProperty 注解来自动补充实体以及其属性的描述和备注。

注解详解

1. @Api
   通过在控制器类上增加 @Api 注解，可以给控制器增加描述和标签信息。

@Api(tags = "用户相关接口", description = "提供用户相关的 Rest API")
public class UserController

@Api其它属性配置：

2. @ApiOperation
   通过在接口方法上增加 @ApiOperation 注解来展开对接口的描述，当然这个注解还可以指定很多内容，我们在下面的相关注解说明章节中详细解释。

@ApiOperation("新增用户接口")
@PostMapping("/add")
public boolean addUser(@RequestBody User user) {
    return false;
}

@ApiOperation其它属性配置：

2.1 @ApiImplicitParams、@ApiImplicitParam

@ApiIgnore: Swagger 文档不会显示拥有该注解的接口。 @ApiImplicitParams: 用于描述接口的非对象参数集。 @ApiImplicitParam: 用于描述接口的非对象参数，一般与 @ApiImplicitParams 组合使用。

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
	@ApiImplicitParam：对单个参数的说明	    
	    name：参数名
	    value：参数的说明、描述
	    required：参数是否必须必填
	    paramType：参数放在哪个地方
	        · query --> 请求参数的获取：@RequestParam
	        · header --> 请求参数的获取：@RequestHeader	      
	        · path（用于restful接口）--> 请求参数的获取：@PathVariable
	        · body（请求体）-->  @RequestBody User user
	        · form（普通表单提交）	   
	    dataType：参数类型，默认String，其它值dataType="Integer"	   
	    defaultValue：参数的默认值

实例

@Api(tags="用户模块")
@Controller
public class UserController {

	@ApiOperation(value="用户登录",notes="随边说点啥")
	@ApiImplicitParams({
		@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
		@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
		@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
	})
	@PostMapping("/login")
	public JsonResult login(@RequestParam String mobile, @RequestParam String password,
	@RequestParam Integer age){
		//...
	    return JsonResult.ok(map);
	}
}

2.2 @ApiResponses、@ApiResponse

@ApiResponses：方法返回对象的说明
	@ApiResponse：每个参数的说明
	    code：数字，例如400
	    message：信息，例如"请求参数没填好"
	    response：抛出异常的类

实例

@Api(tags="用户模块")
@Controller
public class UserController {

	@ApiOperation("获取用户信息")
	@ApiImplicitParams({
		@ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")
	}) 
	@ApiResponses({
		@ApiResponse(code = 200, message = "请求成功"),
		@ApiResponse(code = 400, message = "请求参数没填好"),
		@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
	}) 
	@ResponseBody
	@RequestMapping("/list")
	public JsonResult list(@RequestParam String userId) {
		...
		return JsonResult.ok().put("page", pageUtil);
	}
}

3. @ApiModel 和 @ApiModelProperty
   @ApiModel: 可设置接口相关实体的描述。 @ApiModelProperty: 可设置实体属性的相关描述。

@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户 id")
private int id;
}

参考文献
https://www.jianshu.com/p/6d2beb9dec72
https://blog.csdn.net/xiaojin21cen/article/details/78654652
https://developer.ibm.com/zh/articles/j-using-swagger-in-a-spring-boot-project/