Knife4j增强版Swagger

tags: [swagger]
categories: [工具]

前言

swagger一般都很熟悉了，一个可以生成Rest风格接口文档的工具，虽然使用了侵入代码式的方式，但却减少了重复变更接口带来的繁杂操作，但是在我周围实际使用中，真的很少又在用它来测试接口功能，它的风格似乎不符合国人的审美，更多的是使用PostMan来测试
最近发现了一个新的美化版的Swagger工具，Knif4J，基本可以满足简单的测试需求

官方文档传送门：传送门

配置使用

这里默认用户是JAVA语言，SpringBoot开发的

引入依赖

推荐使用starter依赖，如下

<!-- https://mvnrepository.com/artifact/com.gitee.sophis/spring-boot-knif4j-starter -->
<dependency>
    <groupId>com.gitee.sophis</groupId>
    <artifactId>spring-boot-knif4j-starter</artifactId>
    <version>latest version</version>
</dependency>

或者你也可以使用以下依赖组合，效果是一致的

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.9.2</version>
</dependency>
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>swagger-bootstrap-ui</artifactId>
  <version>${lastVersion}</version>
</dependency>

编写Swagger2Config配置文件

和Swagger2是一致的，这里读取的是yml配置信息，所以多了个yml处理器

@Configuration
@EnableSwagger2
@EnableKnife4j
@Setter
@PropertySource(value = "classpath:config/swagger.yml", factory = YamlPropertyResourceFactory.class)
@ConfigurationProperties(prefix = "swagger")
public class SwaggerConfiguration {
    private String title;
    private String version;
    private String description;
    private String name;
    private String url;
    private String email;
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bwensun.web"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .contact(new Contact(name, url, email))
                .title(title)
                .description(description)
                .termsOfServiceUrl("https://www.zoombar.fun")
                .version(version)
                .build();
    }
}

public class YamlPropertyResourceFactory implements PropertySourceFactory {
    /**
     * Create a {@link PropertySource} that wraps the given resource.
     *
     * @param name     the name of the property source
     * @param encodedResource the resource (potentially encoded) to wrap
     * @return the new {@link PropertySource} (never {@code null})
     * @throws IOException if resource resolution failed
     */
    @Override
    public PropertySource<?> createPropertySource(@Nullable String name, EncodedResource encodedResource) throws IOException {
        String resourceName = Optional.ofNullable(name).orElse(encodedResource.getResource().getFilename());
        //yaml资源文件
        if (Objects.requireNonNull(resourceName).endsWith(".yml") || resourceName.endsWith(".yaml")) {
            List<PropertySource<?>> yamlSources = new YamlPropertySourceLoader().load(resourceName, encodedResource.getResource());
            return yamlSources.get(0);
        } else {//返回空的Properties
            return new PropertiesPropertySource(resourceName, new Properties());
        }
    }
}

swagger:
  title: Zoombar后端服务
  version: 1.0.0
  description: Zoombar游戏论坛
  name: 孙博文
  url: www.bwensun.top
  email: bwensun@foxmail.com

测试使用

可以看到界面还是非常美观的，对于接口也支持了多种数据方式传输进行调试，总的来说还是比较满意的，另外Knife4J也支持接口信息的导出，这边就可以将它视为YAPI一样的接口文档平台来使用

Swagger2注解信息一览

相关

1. knife4j knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案
2. Spring Boot整合Swagger2构建RESTful API