### Configure Application YAML

Source: https://doc.xiaominfo.com/knife4j

Configuration settings for Spring Boot applications to enable Knife4j enhancements and define OpenAPI documentation metadata.

```yaml
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.xiaominfo.knife4j.demo.web
knife4j:
  enable: true
  setting:
    language: zh_cn
```

--------------------------------

### Define REST API with OpenAPI Annotations

Source: https://doc.xiaominfo.com/knife4j

Example of using Spring Web annotations combined with OpenAPI 3 annotations to document REST controllers.

```java
@RestController
@RequestMapping("body")
@Tag(name = "body参数")
public class BodyController {

   @Operation(summary = "普通body请求")
   @PostMapping("/body")
   public ResponseEntity<FileResp> body(@RequestBody FileResp fileResp){
       return ResponseEntity.ok(fileResp);
   }

   @Operation(summary = "普通body请求+Param+Header+Path")
   @Parameters({
           @Parameter(name = "id",description = "文件id",in = ParameterIn.PATH),
           @Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),
           @Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)
   })
   @PostMapping("/bodyParamHeaderPath/{id}")
   public ResponseEntity<FileResp> bodyParamHeaderPath(@PathVariable("id") String id,@RequestHeader("token") String token, @RequestParam("name")String name,@RequestBody FileResp fileResp){
       fileResp.setName(fileResp.getName()+",receiveName:"+name+",token:"+token+",pathID:"+id);
       return ResponseEntity.ok(fileResp);
   }
}
```

--------------------------------

### YAML Configuration for Enhanced Documentation

Source: https://doc.xiaominfo.com/docs/changelog/x/2020-10-26-knife4j-2.0.6-issue

Example of configuring Knife4j document groups and locations within the application.yml file.

```yaml
knife4j:
  enable: true
  documents:
    - group: 2.X版本
      name: 接口签名
      locations: classpath:sign/*
    - group: 2.X版本
      name: 另外文档分组请看这里
      locations: classpath:markdown/*
```

--------------------------------

### Start Knife4jInsight Service

Source: https://doc.xiaominfo.com/docs/middleware-sources/desktop-introduction

Command to initialize and start the Knife4jInsight container service defined in the docker-compose.yml file.

```bash
docker-compose up
```

--------------------------------

### Install Knife4j Microservice Starter

Source: https://doc.xiaominfo.com/docs/changelog/x/2019-12-16-knife4j-2.0.0-issue

Use the microservice-specific starter for environments where the UI is handled by a gateway, minimizing dependencies in individual microservices.

```xml
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-micro-spring-boot-starter</artifactId>
  <version>2.0.0</version>
</dependency>
```

--------------------------------

### Add Knife4j OpenAPI3 Spring Boot Starter (Maven)

Source: https://doc.xiaominfo.com/docs/quick-start

This Maven dependency is used to integrate Knife4j with the OpenAPI3 specification for Spring Boot projects, utilizing the springdoc-openapi framework. This is recommended over the older springfox-based OpenAPI3 support.

```xml
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>
```

--------------------------------

### Configure Knife4j for OpenAPI2

Source: https://doc.xiaominfo.com/docs/quick-start

This YAML configuration enables Knife4j and defines metadata for the OpenAPI2 documentation, including title, description, contact information, version, and license details. It also allows for API grouping based on package.

```yaml
knife4j:
  enable: true
  openapi:
    title: Knife4j官方文档
    description: "`我是测试`,**你知道吗**
    # aaa"
    email: xiaoymin@foxmail.com
    concat: 八一菜刀
    url: https://docs.xiaominfo.com
    version: v4.0
    license: Apache 2.0
    license-url: https://stackoverflow.com/
    terms-of-service-url: https://stackoverflow.com/
    group:
      test1:
        group-name: 分组名称
        api-rule: package
        api-rule-resources:
          - com.knife4j.demo.new3
```

--------------------------------

### Configure Knife4j Dependencies

Source: https://doc.xiaominfo.com/knife4j

Maven and Gradle dependencies for integrating Knife4j with Spring Boot applications. Choose the appropriate starter based on your Spring Boot version and OpenAPI specification preference.

```xml
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>
```

```gradle
implementation("com.github.xiaoymin:knife4j-openapi3-jakarta-spring-boot-starter:4.4.0")
```

```xml
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>
```

--------------------------------

### Install Knife4j Spring Boot Starter

Source: https://doc.xiaominfo.com/docs/changelog/x/2019-12-16-knife4j-2.0.0-issue

Use the starter dependency to integrate Knife4j into a Spring Boot project. This includes the UI components automatically.

```xml
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>2.0.0</version>
</dependency>
```

--------------------------------

### Install Knife4j NuGet Packages

Source: https://doc.xiaominfo.com/docs/action/dotnetcore-knife4j-guid

Commands to install the necessary Swashbuckle and Knife4j UI packages via NuGet Package Manager or .NET CLI.

```powershell
Install-Package Swashbuckle.AspNetCore.Swagger
Install-Package Swashbuckle.AspNetCore.SwaggerGen
Install-Package IGeekFan.AspNetCore.Knife4jUI
```

```bash
dotnet add package Swashbuckle.AspNetCore.Swagger
dotnet add package Swashbuckle.AspNetCore.SwaggerGen
dotnet add package IGeekFan.AspNetCore.Knife4jUI
```

--------------------------------

### Manual Route Configuration Example (YAML)

Source: https://doc.xiaominfo.com/docs/blog/gateway/knife4j-gateway-introduce

An example of defining custom routes for manual aggregation in Knife4j Gateway. This configuration snippet shows how to specify a service name and the URL for its API documentation, which will be directly used by the gateway for aggregation.

```yaml
knife4j:
  gateway:
    enabled: true
    # 选择手动
    strategy: manual
    routes:
      - name: 用户服务
        service-name: user-service
        url: /user/v2/api-docs

```

--------------------------------

### Configure Knife4j and Springdoc-openapi for Spring Boot 3

Source: https://doc.xiaominfo.com/docs/quick-start

This configuration enables Knife4j's enhanced features and sets up springdoc-openapi for Swagger UI and API documentation paths. It specifies group configurations for API matching and scanning.

```yaml
# springdoc-openapi project configuration
sprungdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.xiaominfo.knife4j.demo.web
# knife4j's enhanced configuration, no enhancement needed, can be omitted
knife4j:
  enable: true
  setting:
    language: zh_cn
```

--------------------------------

### Add Knife4j OpenAPI3 Jakarta Spring Boot Starter (Maven)

Source: https://doc.xiaominfo.com/docs/quick-start

This Maven dependency is required to integrate Knife4j with OpenAPI3 specification for Spring Boot 3 projects. It leverages springdoc-openapi and requires JDK 17 or higher.

```xml
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>
```

--------------------------------

### Swagger Configuration with OpenApiExtensionResolver

Source: https://doc.xiaominfo.com/docs/changelog/x/2020-10-26-knife4j-2.0.6-issue

Java configuration class for setting up a Docket with custom extensions for group-based documentation.

```java
@Configuration
@EnableSwagger2WebMvc
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
    private final OpenApiExtensionResolver openApiExtensionResolver;

    @Autowired
    public SwaggerConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        String groupName = "2.X版本";
        return new Docket(DocumentationType.SWAGGER_2)
                .host("https://www.baidu.com")
                .apiInfo(apiInfo())
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.bootstrap.ui.demo.new2"))
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildExtensions(groupName));
    }
}
```

--------------------------------

### Annotate REST Controllers with OpenAPI3 Annotations

Source: https://doc.xiaominfo.com/docs/quick-start

Example of using OpenAPI3 annotations like @Tag, @Operation, @Parameters, and @Parameter to document a REST controller and its endpoints. This is used in conjunction with Knife4j for generating API documentation.

```java
@RestController
@RequestMapping("body")
@Tag(name = "body参数")
public class BodyController {

   @Operation(summary = "普通body请求")
   @PostMapping("/body")
   public ResponseEntity<FileResp> body(@RequestBody FileResp fileResp){
       return ResponseEntity.ok(fileResp);
   }

   @Operation(summary = "普通body请求+Param+Header+Path")
   @Parameters({
           @Parameter(name = "id",description = "文件id",in = ParameterIn.PATH),
           @Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),
           @Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)
   })
   @PostMapping("/bodyParamHeaderPath/{id}")
   public ResponseEntity<FileResp> bodyParamHeaderPath(@PathVariable("id") String id,@RequestHeader("token") String token, @RequestParam("name")String name,@RequestBody FileResp fileResp){
       fileResp.setName(fileResp.getName()+',receiveName:'+name+',token:'+token+',pathID:'+id);
       return ResponseEntity.ok(fileResp);
   }
}
```

--------------------------------

### Install Dependencies for Knife4j-vue

Source: https://doc.xiaominfo.com/docs/community/contributing

Command to install required Node.js dependencies for the frontend project.

```shell
npm install
```

--------------------------------

### Configuring Knife4j UI Middleware in Startup (C#)

Source: https://doc.xiaominfo.com/docs/action/dotnetcore-knife4j-how

Example of configuring and using the Knife4j UI middleware in the Startup.cs file of a .NET application. It shows how to set the route prefix and define Swagger endpoints.

```csharp
app.UseKnife4UI(c =>
{
    c.RoutePrefix = ""; // serve the UI at root
    c.SwaggerEndpoint("/v1/api-docs", "V1 Docs");
    c.SwaggerEndpoint("/gp/api-docs", "登录模块");
});

```

--------------------------------

### Swagger Root Object Extension Example (JSON)

Source: https://doc.xiaominfo.com/docs/action/springfox/springfox13

An example of a Swagger JSON document demonstrating the use of vendor extensions in the root object. Vendor extensions allow for custom properties to be added, provided they start with 'x-'.

```json
{
    "swagger": "2.0",
    "info": {
        "description": "<div style='font-size:14px;color:red;'>swagger-bootstrap-ui-demo RESTful APIs</div>",
        "version": "1.0",
        "title": "swagger-bootstrap-ui很棒~~~！！！",
        "termsOfService": "http://www.group.com/",
        "contact": {
            "name": "group@qq.com"
        }
    },
    "host": "127.0.0.1:8999",
    "basePath": "/",
    "tags": [
        {
            "name": "1.8.2版本",
            "description": "Api 182 Controller"
        }
    ],
    "paths": {
        "/2/api/new187/postRequest": {
            "post": {
                "tags": [
                    "api-1871-controller"
                ],
                "summary": "版本2-post请求参数Hidden属性是否生效",
                "operationId": "postRequestUsingPOST_1",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "*/*"
                ],
                "parameters": [
                    {
                        "in": "body",
                        "name": "model187",
                        "description": "model187",
                        "required": true,
                        "schema": {
                            "originalRef": "Model187",
                            "$ref": "#/definitions/Model187"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "originalRef": "Rest«Model187»",
                            "$ref": "#/definitions/Rest«Model187»"
                        }
                    },
                    "201": {
                        "description": "Created"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "Not Found"
                    }
                },
                "security": [
                    {
                        "BearerToken": [
                            "global"
                        ]
                    },
                    {
                        "BearerToken1": [
                            "global"
                        ]
                    }
                ],
                "deprecated": false
            }
        }
    },
    "securityDefinitions": {
        "BearerToken": {
            "type": "apiKey",
            "name": "Authorization",
            "in": "header"
        }
    },
    "definitions": {
        "AInfoVo": {
            "type": "object",
            "required": [
                "aId",
                "bList"
            ],
            "properties": {
                "aId": {
                    "type": "string",
                    "description": "A记录主键"
                },
                "bList": {
                    "type": "object",
                    "description": "B信息Map, key为BInfoVo的主键pkId",
                    "additionalProperties": {
                        "originalRef": "BInfoVo",
                        "$ref": "#/definitions/BInfoVo"
                    }
                }
            },
            "title": "AInfoVo",
            "description": "A信息"
        },
        "ActInteger": {
            "type": "object",
            "properties": {
                "doub1": {
                    "type": "number",
                    "format": "double",
                    "description": "double类型属性"
                },
                "float1": {
                    "type": "number",
                    "format": "float",
                    "description": "float类型属性"
                },
                "name": {
                    "type": "string"
                },
                "number": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Long类型"
                },
                "price": {
                    "type": "number"
                }
            }
        }
    }
}
```

--------------------------------

### Spring Plugin System: Plugin Interface Usage Example (Java)

Source: https://doc.xiaominfo.com/docs/action/springfox/springfox3

Demonstrates the typical usage pattern of the `Plugin<S>` interface within the Spring Plugin system. It shows how to retrieve a list of plugins and invoke their `supports` and `doSomeThing` methods based on a delimiter.

```java
List<Plugin<S>> plugins=plugin.getPlugins();  
S delimiter;  
for(Plugin<S> p:plugins){  
    if(p.supports(delimiter)){  
        p.doSomeThing();//  
    }  
}  

```

--------------------------------

### Maven Dependencies for Spring Plugin Example (XML)

Source: https://doc.xiaominfo.com/docs/action/springfox/springfox3

Provides the necessary Maven dependencies to set up a project using the Spring Plugin core library, along with Spring core and logging frameworks like Logback and SLF4j.

```xml
<properties>
    <logback.version>1.2.3</logback.version>
    <org.slf4j.version>1.7.21</org.slf4j.version>
</properties>

<dependencies>
    <!-- https://mvnrepository.com/artifact/junit/junit -->
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.8.2</version>
        <scope>test</scope>
    </dependency>

    <!-- https://mvnrepository.com/artifact/org.springframework/spring-core -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-core</artifactId>
        <version>4.0.9.RELEASE</version>
    </dependency>

    <!-- https://mvnrepository.com/artifact/org.springframework.plugin/spring-plugin-core -->
    <dependency>
        <groupId>org.springframework.plugin</groupId>
        <artifactId>spring-plugin-core</artifactId>
        <version>1.2.0.RELEASE</version>
    </dependency>

    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>${org.slf4j.version}</version>
    </dependency>
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>jcl-over-slf4j</artifactId>
        <version>${org.slf4j.version}</version>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>${logback.version}</version>
        <exclusions>
            <exclusion>
                <groupId>javax.mail</groupId>
                <artifactId>mail</artifactId>
            </exclusion>
            <exclusion>
                <groupId>javax.jms</groupId>
                <artifactId>jms</artifactId>
            </exclusion>
            <exclusion>
                <groupId>com.sun.jdmk</groupId>
                <artifactId>jmxtools</artifactId>
            </exclusion>
            <exclusion>
                <groupId>com.sun.jmx</groupId>
                <artifactId>jmxri</artifactId>
            </exclusion>
        </exclusions>
        <scope>runtime</scope>
    </dependency>
</dependencies>

```

--------------------------------

### Apply @ParameterObject Annotation

Source: https://doc.xiaominfo.com/docs/faq/v4/knife4j-parameterobject-flat-param

Use the @ParameterObject annotation on controller method parameters to ensure correct parsing of GET request objects.

```java
@Operation(summary = "Get 请求", tags = "对接口分组", description = "对接口的作用进行描述")
@RequestMapping(value = "/api/v1/open-api", method = RequestMethod.GET)
public R<GetDTO> get(@ParameterObject GetDTO dto) {
    return R.ok(dto);
}
```

--------------------------------

### Integrate Knife4j Spring Boot Starter

Source: https://doc.xiaominfo.com/docs/changelog/x/2019-12-23-knife4j-2.0.1-issue

Use the knife4j-spring-boot-starter dependency for quick integration in Spring Boot applications. This starter package includes the UI components by default.

```xml
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>2.0.1</version>
</dependency>
```

--------------------------------

### 运行Algolia Docker爬虫

Source: https://doc.xiaominfo.com/docs/action/others/doc-search

使用Docker镜像运行Algolia爬虫工具，将本地或自定义网站数据索引至Algolia控制台。需要配置.env文件包含APPLICATION_ID、API_KEY和CONFIG规则。

```bash
docker run -it --env-file=.env algolia/docsearch-scraper
```

--------------------------------

### Integrate Knife4j for Microservices

Source: https://doc.xiaominfo.com/docs/changelog/x/2019-12-23-knife4j-2.0.1-issue

In a microservice architecture, use the micro-spring-boot-starter dependency. This allows for enhanced features without bundling the UI in every microservice, typically intended for use at the gateway level.

```xml
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-micro-spring-boot-starter</artifactId>
  <version>2.0.1</version>
</dependency>
```

--------------------------------

### Add Knife4j OpenAPI3 Jakarta Spring Boot Starter (Gradle)

Source: https://doc.xiaominfo.com/docs/quick-start

This Gradle dependency is required to integrate Knife4j with OpenAPI3 specification for Spring Boot 3 projects. It leverages springdoc-openapi and requires JDK 17 or higher.

```gradle
implementation("com.github.xiaoymin:knife4j-openapi3-jakarta-spring-boot-starter:4.4.0")
```

--------------------------------

### 文档聚合服务依赖引入

Source: https://doc.xiaominfo.com/docs/action/springcloud-gateway

为文档聚合服务引入Eureka客户端、Gateway网关以及Knife4j Spring Boot Starter的依赖。

```xml
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>
```

--------------------------------

### Initialize Springfox Documentation via SmartLifecycle

Source: https://doc.xiaominfo.com/docs/action/springfox/springfox7

The DocumentationPluginsBootstrapper class implements the SmartLifecycle interface to trigger the documentation initialization process once the Spring context is refreshed. It manages plugin instances and iterates through configured Docket beans to scan and generate API documentation.

```java
@Component
public class DocumentationPluginsBootstrapper implements SmartLifecycle {
  private static final Logger log = LoggerFactory.getLogger(DocumentationPluginsBootstrapper.class);
  private final DocumentationPluginsManager documentationPluginsManager;
  private final List<RequestHandlerProvider> handlerProviders;

  @Override
  public void start() {
    if (initialized.compareAndSet(false, true)) {
      log.info("Context refreshed");
      List<DocumentationPlugin> plugins = pluginOrdering()
          .sortedCopy(documentationPluginsManager.documentationPlugins());
      log.info("Found {} custom documentation plugin(s)", plugins.size());
      for (DocumentationPlugin each : plugins) {
        DocumentationType documentationType = each.getDocumentationType();
        if (each.isEnabled()) {
          scanDocumentation(buildContext(each));
        } else {
          log.info("Skipping initializing disabled plugin bean {} v{}",
                   documentationType.getName(), documentationType.getVersion());
        }
      }
    }
  }
}
```

--------------------------------

### CustomerService Using PluginRegistry (Java)

Source: https://doc.xiaominfo.com/docs/action/springfox/springfox3

This Java class demonstrates how to use the PluginRegistry to inject and iterate over available MobileIncrementBusiness plugins. The `increments` method dynamically applies all registered plugins to a given mobile customer and recharge amount.

```java
@Component  
public class CustomerService {  
  
    @Autowired  
    private PluginRegistry<MobileIncrementBusiness,MobileCustomer> mobileCustomerPluginRegistry;  
    
  
    public void increments(MobileCustomer mobileCustomer,int money){  
        //获取插件  
        List<MobileIncrementBusiness> plugins=mobileCustomerPluginRegistry.getPlugins();  
        for (MobileIncrementBusiness incrementBusiness:plugins){  
            //对人员进行充值  
            incrementBusiness.increment(mobileCustomer,money);  
        }  
    }  
  
}
```

--------------------------------

### 配置Maven依赖以启用Knife4j聚合

Source: https://doc.xiaominfo.com/docs/action/aggregation-cloud

在Spring Boot项目的pom.xml中引入knife4j-aggregation-spring-boot-starter依赖。该依赖是实现OpenAPI文档聚合的核心组件。

```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.0</version>
        <relativePath/>
    </parent>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-aggregation-disk-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
            <version>2.0.8</version>
        </dependency>
    </dependencies>
</project>
```

--------------------------------

### 定义 Swagger 请求参数示例

Source: https://doc.xiaominfo.com/docs/features/requestCache

展示了如何通过 @ApiModelProperty 注解设置字段的 example 值，从而影响 Knife4j 的默认缓存行为。当提供 example 时，Knife4j 将始终使用该值；否则，将缓存用户在调试界面输入的值。

```java
public class SwaggerRequestBody{  
      
    @ApiModelProperty(value="姓名",example="张飞")  
    private String name;  
      
    //more...  
}  
```

```java
public class SwaggerRequestBody{  
      
    @ApiModelProperty(value="姓名")  
    private String name;  
      
    //more...  
}  
```

--------------------------------

### Java Entity with Example Value - Knife4j

Source: https://doc.xiaominfo.com/docs/features/requestcache

This Java code snippet demonstrates a class with an `ApiModelProperty` annotation that includes an `example` value. When a field has an example value, Knife4j will use this value as the default in the request parameters, overriding any cached values.

```java
public class SwaggerRequestBody{
  
    @ApiModelProperty(value="姓名",example="张飞")
    private String name;
  
    //more...
}
```

--------------------------------

### Java Model with Corrected 'example' Attribute (Java)

Source: https://doc.xiaominfo.com/docs/faq/knife4j-exception

Shows the corrected version of the Java model where the `example` attribute is removed from the `@ApiModelProperty` for the collection property. This allows `springfox-swagger2` to handle the JSON generation correctly, preventing parsing errors.

```java
@ApiModel(description = "客户字段分组模型",value = "CrmFieldGroupResponse")
public class CrmFieldGroupResponse {

    @ApiModelProperty(value = "客户字段分组ID")
    private int id;

    @ApiModelProperty(value = "客户字段分组名称")
    private String name;

    @ApiModelProperty(value = "客户字段数据")
    private List<CrmFieldResponse> fields;

}
```

--------------------------------

### Java Model with Invalid 'example' Attribute (Java)

Source: https://doc.xiaominfo.com/docs/faq/knife4j-exception

Illustrates a common cause of invalid JSON responses: the use of the `example` attribute within `@ApiModelProperty` for collection types. This can lead to `JSON.parse()` failures in frontend components like Knife4j.

```java
@ApiModel(description = "客户字段分组模型",value = "CrmFieldGroupResponse")
public class CrmFieldGroupResponse {

    @ApiModelProperty(value = "客户字段分组ID")
    private int id;

    @ApiModelProperty(value = "客户字段分组名称")
    private String name;

    @ApiModelProperty(value = "客户字段数据",example = "{'id':'xxx'}")
    private List<CrmFieldResponse> fields;

}
```

--------------------------------

### Maven依赖配置 - service-doc工程

Source: https://doc.xiaominfo.com/docs/action/aggregation-eureka

在service-doc工程的pom.xml文件中引入knife4j-aggregation-spring-boot-starter依赖，用于实现Knife4j的聚合功能。此依赖是聚合Eureka注册中心文档的基础。

```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.xiaominfo.swagger</groupId>
        <artifactId>knife4j-aggregation-eureka-demo</artifactId>
        <version>1.0</version>
        <relativePath>../pom.xml</relativePath> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.xiaominfo.swagger</groupId>
    <artifactId>service-doc</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>service-doc</name>
    <description>Eureka聚合</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
            <version>2.0.8</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>
```

--------------------------------

### Java Entity without Example Value - Knife4j

Source: https://doc.xiaominfo.com/docs/features/requestcache

This Java code snippet shows a class where an `ApiModelProperty` annotation lacks an `example` value. In this scenario, Knife4j will use the last-filled cached value for the parameter during subsequent debugging requests, as no default is provided by the backend.

```java
public class SwaggerRequestBody{
  
    @ApiModelProperty(value="姓名")
    private String name;
  
    //more...
}
```

--------------------------------

### Maven依赖配置 - Spring Boot

Source: https://doc.xiaominfo.com/docs/action/aggregation-disk

配置Spring Boot项目以使用Knife4j聚合功能。此pom.xml文件引入了Spring Boot Web启动器、Knife4j聚合启动器以及测试启动器。

```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.0</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-aggregation-disk-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>knife4j-aggregation-disk-demo</name>
    <description>通过基于Spring Boot的工程聚合任意微服务接口文档</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
            <version>2.0.8</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>
```

--------------------------------

### ApiDescription Class Structure in Springfox

Source: https://doc.xiaominfo.com/docs/action/springfox/springfox12

Defines the ApiDescription class, which holds information about an API endpoint, including its group name, path, description, and a collection of operations. An API can have multiple operations (e.g., GET, POST) associated with it.

```java
public class ApiDescription {
  //分组名称
  private final String groupName;
  //路径
  private final String path;
  //描述
  private final String description;
  //操作信息集合
  //一个接口有可能存在多个请求方法类型,即：GET、POST、PUT、DELETE等,所以这里也是1：N的映射关系
  private final List<Operation> operations;
  //是否隐藏
  private final Boolean hidden;

  //getter and setters....
}
```

--------------------------------

### POST /description

Source: https://doc.xiaominfo.com/docs/blog/add-authorization-header

An example of an endpoint secured with an Authorization header using the @SecurityRequirement annotation.

```APIDOC
## POST /description

### Description
An example endpoint demonstrating how to apply security requirements to a specific operation to ensure the Authorization header is included in the Knife4j debug interface.

### Method
POST

### Endpoint
/description

### Parameters
#### Request Body
- **configPageParam** (Object) - Required - The configuration parameters object.

### Request Example
{
  "param": "value"
}

### Response
#### Success Response (200)
- **configPageParam** (Object) - Returns the submitted configuration object.

#### Response Example
{
  "param": "value"
}
```

--------------------------------

### 微服务接口依赖配置 (Spring Cloud)

Source: https://doc.xiaominfo.com/docs/action/springcloud-gateway

为微服务引入Spring Boot Web、Eureka客户端以及Knife4j微服务Starter的依赖。

```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-micro-spring-boot-starter</artifactId>
</dependency>
```

--------------------------------

### Security Configuration Setup

Source: https://doc.xiaominfo.com/docs/blog/add-authorization-header

How to define global security schemes in OpenAPI3 using SpringDoc.

```APIDOC
## Configuration: Global Security Scheme

### Description
Define the security scheme in the components section of the OpenAPI bean to enable Authorization support.

### Code Example
```java
@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION))
            .components(new Components().addSecuritySchemes(HttpHeaders.AUTHORIZATION, 
                new SecurityScheme()
                    .name(HttpHeaders.AUTHORIZATION)
                    .type(SecurityScheme.Type.HTTP)
                    .scheme("bearer")));
}
```
```