SpringBoot 集成 Swagger踩坑记录

添加依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.4</version>
</dependency>

Swagger 配置

创建如下的配置类 Swagger2Config.java，@Configuration 使应用启动的时候就加载这个配置类，@EnableSwagger2 启用 swagger。

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        TypeResolver typeResolver = new TypeResolver();
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .alternateTypeRules(
                        newRule(typeResolver.resolve(DeferredResult.class,
                                typeResolver.resolve(ResponseEntity.class, WildcardType.class)),
                                typeResolver.resolve(WildcardType.class)))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.pactera.cr"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("人行征信").description("人行征信解析查询")
                .version("1.0").build();
    }
}

1. API 设计规范

下面是 OpenAPI 规范中建议的 API 基本路径设计规范。

https://api.example.com/v1/users?role=admin&status=active
\________________________/\____/ \______________________/
         server URL       endpoint    query parameters
                            path

server URL: 一般包含IP/域名、端口、版本。
endpoint path: 端点路径对应具体的接口方法。
query parameters: 请求参数

2. Swagger

Swagger是一个实现了OpenAPI(OpenAPI Specification)规范的工具集。OpenAPI是Linux基金会的一个项目，其目的是通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。
Swagger工具集包含：

• Swagger Editor(开源)： Swagger Editor允许您在浏览器中编辑YAML中的OpenAPI规范并实时预览文档。
• Swagger UI(开源)： Swagger UI是HTML，Javascript和CSS资产的集合，可以从符合OAS标准的API动态生成漂亮的文档。
• Swagger Codegen(开源)：允许根据OpenAPI规范自动生成API客户端库（SDK生成），服务器存根和文档。
• Swagger Inspector： API测试工具，可让您验证您的API并从现有API生成OpenAPI定义
• SwaggerHub： API设计和文档，为使用OpenAPI的团队构建。

项目集成 knife4j（knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案），启动后通过 http://[ip]:[端口]/doc.html 路径可以访问API管理页面。

2.1 常用注解说明

注解	示例	描述
@Api	@Api(value = “用户操作 API(v1)”, tags = “用户操作接口”)	用在接口类上，为接口类添加描述。
@ApiOperation	@ApiOperation(value = “新增用户”)	用在方法上，未方法添加描述
@ApiModel	@ApiModel(value = “用户对象”)	描述一个实体对象
@ApiModelProperty	@ApiModelProperty(value = “用户ID”, dataType = ,required = true, example = “1000”)	描述属性信息，执行描述，是否必须，给出示例
@ApiParam	@ApiParam(value = “用户名”, required = true)	描述单个参数

2.2 注解使用示例

2.2.1 @Api

该注解将一个Controller（Class）标注为一个swagger资源（API）。该注解包含以下重要属性：

• tags
  API分组标签，具有相同标签的API将会被归并在一组内展示。默认情况下同一个Controller下的接口在同一组内。

@RestController
@Api(tags = "文档管理接口")
public class DocumentController {
    ...
}

---

2.2.2 @ApiOperation

该注解用在方法上，说明方法的作用。该注解包含以下重要属性：

• value
  方法名，显示在API文档的菜单中。
• notes
  方法描述，显示在API文档对应的接口详情页中。
• hidden
  hidden = true, 表示对应的接口不会显示在API文档中。

@GetMapping("/page")
@ApiOperation(value = "查询文档列表", notes = "xxxx接口发布说明")
public Response<IPage<Document>> page(@RequestBody Page<Document> page , @RequestHeader HttpHeaders header) {
    ...
}

---

2.2.3 @ApiModel 和 @ApiModelProperty

@ApiModel用在实体类Model上，标记该类为Swagger的解析类。
@ApiModelProperty用在实体类的属性上，用于描述属性信息。该注解包含以下重要属性：

• value
  属性的简要说明
• required
  是否为必传参数,false:非必传参数; true:必传参数
• hidden
  隐藏模型属性，false:不隐藏; true:隐藏
• example
  属性的示例值

@Data
@ApiModel
public class SendSingleSmsReq implements Serializable {

    @ApiModelProperty(value = "必输-调用流水号：产品编码+手机号+时间戳", required = true, example = "sms202008310000")
    @NotEmpty(message = "请输入调用流水号")
    private String serialNo;
    ...
}

2.3 接口测试

1. 接口详情页面选择调试；
2. 选择参数类型；
3. 填写测试参数；
4. 发送测试请求。
   

3. 踩坑记录

乱码问题

问题描述： swagger API 管理页面中文乱码
解决方法：
修改 Springboot 的编码方式，解决 Controller 到页面的浏览器的乱码问题。

spring:
  http:
    encoding:
      charset: UTF-8
      force: true
      enabled: true

参数命名不规范问题

问题描述：
请求实体中属性的命名如果不符合驼峰命名规则，会导致@ApiModelProperty失效并且对应属性在API文档中会被强制转成驼峰命名的变量，同时后台也无法接收到命名不规范的参数。
如果由于某些特殊原因实体中的属性就是无法按照驼峰命名，该怎么办？
解决方法：
在成员变量上加上@JsonProperty注解并在它对应的get和set方法上加上@JsonIgnore注解

@JsonProperty("RequestParams")
@ApiModelProperty(value = "必输-业务参数", required = true)
private T RequestParams;

@JsonIgnore
public T getRequestParams() {
    return RequestParams;
}

@JsonIgnore
public void setRequestParams(T requestParams) {
    RequestParams = requestParams;
}