```xml
<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-openapi3-knife4j</artifactId>
</dependency>
```

#### 1、描述

（v3.8.1 后支持）文档扩展插件，为 Solon Docs 提供基于 swagger3 + knife4j（[代码仓库](https://gitee.com/xiaoym/knife4j)）的框架适配，以提供接口文档支持。项目启动后，通过 "/doc.html" 打开文档。

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



| 路径 | 备注 | 
| -------- | -------- | 
| `/doc.html`       | 静态    | 
| `/webjars/*`     | 静态    | 
| `/img/*`           | 静态    | 
| | | 
| `/swagger/*`                 | 动态      | 
| `/v3/api-docs/*`     | 动态     | 



更多学习内容，参考：

* [文档摘要的配置与构建](/article/796)
* [文档摘要的分布式聚合](/article/797)

#### 2、配置说明

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

```yaml
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、使用说明

* 构建文档摘要（可以有多个）

```java
@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"); //可以加多条，以包名为单位

    }
}
```

* 简单的应用（给接口上加注解，可以是最少量）

```java
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.Operation;
import org.noear.solon.annotation.Body;
import org.noear.solon.annotation.Controller;
import org.noear.solon.annotation.Mapping;
import org.noear.solon.annotation.Post;
import org.noear.solon.core.handle.Result;

@Tag(name ="控制器")
@Mapping("/demo")
@Controller
public class DemoController {
    @Operation(summary = "接口")
    @Mapping("hello")
    public Result hello(User user) { //以普通参数提交
        return null;
    }

    @Operation(summary = "接口")
    @Post
    @Mapping("hello2")
    public Result hello2(@Body User user) { //以 json body 提交
        return null;
    }
}
```

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

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

```java
import org.noear.solon.annotation.Bean;
import org.noear.solon.annotation.Configuration;
import org.noear.solon.docs.DocDocket;

@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](https://gitee.com/noear/solon-examples/tree/main/a.Doc/demoA002-openapi2_knife4j)