一、简介
Swaggerknife4j是一个基于swagger的API文档生成工具，它能够根据Java代码生成RESTful API文档，并提供一些额外的功能，例如在线调试和测试接口。它可以让开发人员轻松地理解API，以及与API交互的方式。
Swaggerknife4j不仅提供了更好的文档和测试接口功能，还针对swagger-ui做了一些优化，例如减少加载时间、增加搜索功能，并且它支持自定义错误响应和修改默认UI。
一般情况下，当使用swagger生成API文档时，需要为每个API编写注释，并且将文档与代码保持同步。这使得文档维护变得非常繁琐，并且容易出现错误。而swaggerknife4j可以帮助您快速自动生成API文档，并与代码保持同步。
二、安装和配置
安装swaggerknife4j非常简单，只需要在Maven POM文件中添加以下依赖项：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.9</version>
</dependency>
默认情况下，swaggerknife4j使用的是swagger-ui 2.x版本，因此您还需要将以下的依赖项添加到您的Maven POM文件中：
<dependency>
<groupId>org.webjars</groupId>
<artifactId>swagger-ui</artifactId>
<version>2.2.10</version>
</dependency>
然后，您需要在你的SpringBoot项目中添加swagger2和swagger-ui的相关配置信息：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controllers"))
.paths(PathSelectors.any())
.build()
.securitySchemes(Lists.newArrayList(apiKey()));
}
private ApiKey apiKey() {
return new ApiKey("token", "token", "header");
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot API文档")
.description("API文档")
.version("1.0")
.build();
}
}
以上的代码使用了演示的SpringBoot项目的controller包下的Restful API注解作为API的展示范例。
注意事项：
- 在createRestApi（）方法中添加自己的API组名，或者更换具体项目的包下API
- 在apiKey方法中添加自定义参数以实现token，然后就可以在REST API中使用header参数token作为Authentication信息了。
三、使用说明
在完成安装和配置之后，您可以访问http://localhost:8080/swagger-ui.html来查看生成的API文档。文档会列出所有API，它们的参数和返回类型信息，以及如何在API调试界面中调用它们。
swaggerknife4j还提供了一些自定义配置选项，例如更改API的描述信息、设置API的默认响应、隐藏API、设置API访问控制和设置全局响应headers。这些配置选项可以通过使用@ControllerAdvice或@GlobalResponseWrapper注释来实现。
以下是一个使用@ControllerAdvice来设置全局响应headers的示例代码：
@ControllerAdvice
public class GlobalResponseHeaders {
@ModelAttribute
public void setHeaders(Model model) {
model.addAttribute("responseHeaders", ImmutableMap.of(
"X-Content-Type-Options", "nosniff",
"X-Frame-Options", "DENY"
));
}
}
更多示例请参考swaggerknife4j的官方文档。
四、样式优化
你可以使用自定义Swagger主题来定制您的API文档的外观，并增加一些额外的功能。例如，在您的API文档中添加标签、增加搜索功能或者自定义生成的文档的样式。
下面是一个创建自定义Swagger主题的示例代码：
@Configuration
@EnableSwaggerBootstrapUI
public class SwaggerBootstrapUiConfig {
@Bean
public SwaggerResourcesProvider swaggerResourcesProvider() {
return new SwaggerBootstrapUiResourceProvider();
}
@Bean
public SwaggerBootstrapUiConfig swaggerBootstrapUiConfig() {
return SwaggerBootstrapUiConfigBuilder.builder()
.title("API文档")
.description("API文档")
.version("1.0")
.build();
}
}
以上代码中使用了SwaggerBootstrapUiConfigBuilder，SwaggerBootstrapUiResourceProvider和SwaggerBootstrapUiConfig等类，来设置生成文档的样式。
更多示例请参考swaggerknife4j的官方文档。
五、总结
Swaggerknife4j是一个非常优秀的基于swagger的API文档生成工具，它不仅提供了更好的文档和测试接口，而且在swagger-ui上做了很多优化并支持自定义配置选项。同时，它也可以帮助开发人员减轻文档维护的负担，并与代码保持同步。因此，对于需要自动生成API文档的开发人员来说，swaggerknife4j是一个非常不错的选择。
