了解swaggerknife4j：一个基于swagger的API文档生成工具

一、简介

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是一个非常不错的选择。

原创文章，作者：小蓝，如若转载，请注明出处：https://www.506064.com/n/151385.html