Solon v3.0.3

solon-openapi2-knife4j

</> markdown

用于替代 solon-swagger2-knife4j，v2.4.0 后支持

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-openapi2-knife4j</artifactId>
</dependency>

1、描述

文档扩展插件，为 Solon Docs 提供基于 swagger2 + knife4j（代码仓库）的框架适配，以提供接口文档支持。项目启动后，通过 "/doc.html" 打开文档。

如果有签权框架，或过滤器的，需要排除路径：

  • "/doc.html"
  • "/swagger-resources"
  • "/swagger/*"

更多学习内容，参考：

2、配置说明

主要是关于 “knife4j” 的配置，可配置项具体参考 “OpenApiExtensionResolver” 类里的配置注入字段。

knife4j.enable: true
knife4j.basic.enable: true
knife4j.basic.username: admin
knife4j.basic.password: 123456
knife4j.setting.enableOpenApi: false
knife4j.setting.enableSwaggerModels: false
knife4j.setting.enableFooter: false

3、使用说明

  • 构建文档摘要（可以有多个）
@Configuration
public class DocConfig {

    // knife4j 的配置，由它承载
    @Inject
    OpenApiExtensionResolver openApiExtensionResolver;

    /**
     * 简单点的
     */
    @Bean("appApi")
    public DocDocket appApi() {
        //根据情况增加 "knife4j.setting" （可选）
        return new DocDocket()
                .basicAuth(openApiExtensionResolver.getSetting().getBasic())
                .vendorExtensions(openApiExtensionResolver.buildExtensions())
                .groupName("app端接口")
                .schemes(Scheme.HTTP)
                .apis("com.swagger.demo.controller.app");

    }

    /**
     * 丰富点的
     */
    @Bean("adminApi")
    public DocDocket adminApi() {
        //根据情况增加 "knife4j.setting" （可选）
        return new DocDocket()
                .basicAuth(openApiExtensionResolver.getSetting().getBasic())
                .vendorExtensions(openApiExtensionResolver.buildExtensions())
                .groupName("admin端接口")
                .info(new ApiInfo().title("在线文档")
                        .description("在线API文档")
                        .termsOfService("https://gitee.com/noear/solon")
                        .contact(new ApiContact().name("demo")
                                .url("https://gitee.com/noear/solon")
                                .email("demo@foxmail.com"))
                        .version("1.0"))
                .schemes(Scheme.HTTP, Scheme.HTTPS)
                .globalResponseInData(true)
                .globalResult(Result.class)
                .apis("com.swagger.demo.controller.admin"); //可以加多条，以包名为单位

    }
}
  • 简单的应用（给接口上加注解，可以是最少量）
@Api("控制器")  //v2.3.8 之前要用：@Api(tags = "控制器")
@Mapping("/demo")
@Controller
public class DemoController {
    @ApiOperation("接口")
    @Mapping("hello")
    public Result hello(User user) { //以普通参数提交
        return null;
    }
    
    @ApiOperation("接口")
    @Post
    @Mapping("hello2")
    public Result hello2(@Body User user) { //以 json body 提交
        return null;
    }
}

4、分布式服务（或微服务）接口文档聚合

使用 upstream 方法，配置文档上游地址。详情参考：《文档摘要的分布式聚合》

@Configuration
public class DocConfig {
    @Bean("appApi")
    public DocDocket appApi() {
        //例：使用直接地址
        return new DocDocket()
                .groupName("app端接口")
                .upstream("http://localhost:8081", "/app-api", "swagger/v2?group=appApi"); 
    }

    @Bean("adminApi")
    public DocDocket adminApi() {
        //例：使用服务名（需要注册与发现服务配合）
        return new DocDocket()
                .groupName("admin接口")
                .upstream("admin-api", "/admin-api", "swagger/v2?group=adminApi"); 
    }
}

具体可参考：

https://gitee.com/noear/solon-examples/tree/main/a.Doc/demoA002-openapi2_knife4j