在前端未开发出来时，由于不能前后端联调，后端程序员调试接口会比较麻烦。Swagger能够帮助后端程序员调试接口。只需要按照Swagger的规范去定义接口及相关信息，就可以做到生成接口文档，以及在线接口调试页面。但实际开发时不会直接使用Swagger，而是使用Knife4j，它是为Java MVC框架集成Swagger生成API文档的增强解决方案。
在项目中使用Knife4j分三步：
- 引入Knife4j的相关依赖：
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.2</version>
</dependency>
- 在配置类中加入Knife4j加入相关配置，通常该配置类名为WebMvcConfiguration。或者在配置文件中加入相关配置。
/*** 通过knife4j生成接口文档* @return*/
@Bean // 在配置类中需要将Docket注册成Bean
public Docket docket() {log.info("准备生成接口文档...");ApiInfo apiInfo = new ApiInfoBuilder().title("接口文档标题") // 如XX项目接口文档.version("指定版本号") // 如当前已经开发到了2.0版本就指定2.0.description("接口文档描述信息") // 文档描述信息.build();Docket docket = new Docket(DocumentationType.SWAGGER_2).groupName("指定组名") // 开发时可能有多个接口文档，因此需要给这些接口文档分组.apiInfo(apiInfo).select().apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin")) // 指定扫描的包.paths(PathSelectors.any()).build();return docket;
}
- 在配置类中设置静态资源映射，通常该配置类名为WebMvcConfiguration，这部分为固定代码。在配置文件中配置的Knife4j不需要进行这一步。
/*** 设置静态资源映射* @param registry*/
protected void addResourceHandlers(ResourceHandlerRegistry registry) {log.info("开始设置静态资源映射...");registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
配置好Knife4j后访问localhost:8080/doc.html即可。
在需要调试的接口上加上相关注解。常用注解有：
| 注解 | 说明 |
|---|---|
| @Api(tags = “XX接口”) | 加在类上，描述某一个模块的接口，例如员工相关接口 |
| @ApiModel | 加在类上，对实体类进行说明，例如entity、DTO、VO |
| @ApiModelProperty | 加在属性上，对实体类属性进行说明，描述属性信息 |
| @ApiOperation(value = “XX功能”) | 加载方法上，描述具体接口功能，例如员工登录 |