配置说明

forge-swagger 自身没有提供 @ConfigurationProperties 配置类，所有可配置项都来自它依赖的 springdoc-openapi-starter-webmvc-ui 与 Knife4j。

常用 application.yml 配置

yaml

springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
  group-configs:
    - group: default
      paths-to-match: /**
      packages-to-scan: com.demo.app.controller

knife4j:
  enable: true
  setting:
    language: zh_cn
  production: false

springdoc 关键项

配置项	作用	默认值
`springdoc.api-docs.enabled`	是否启用 OpenAPI JSON 端点	true
`springdoc.api-docs.path`	OpenAPI JSON 路径	`/v3/api-docs`
`springdoc.swagger-ui.enabled`	是否启用原生 Swagger UI	true
`springdoc.swagger-ui.path`	Swagger UI 入口	`/swagger-ui.html`
`springdoc.group-configs`	多分组配置，常用于按业务域拆分文档	无
`springdoc.packages-to-scan`	限制扫描包，减少无关接口	全部

knife4j 关键项

配置项	作用	默认值
`knife4j.enable`	总开关	true
`knife4j.setting.language`	UI 语言 zh_cn / en	en
`knife4j.production`	生产环境模式，开启后访问需鉴权	false

完整配置见 springdoc 官方文档与 Knife4j 官方文档。

覆盖默认 OpenAPI Bean

本模块默认的 OpenAPI Bean 是这样的：

java

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI().info(apiInfo())
            .servers(List.of(new Server().url("http://localhost:18080").description("本地开发环境")));
}

private Info apiInfo() {
    return new Info()
            .title("优雅代码实战工坊 API")
            .description("基于Spring Boot 3 + JDK17")
            .version("1.0.0")
            .contact(new Contact().name("cv大魔王").url("https://github.cn/cvking"))
            .license(new License().name("MIT License").url("https://opensource.org/licenses/MIT"));
}

这些字段当前是硬编码的。业务方想替换，最直接的做法是在自己的 @Configuration 类里声明同名 Bean 覆盖：

java

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.*;
import io.swagger.v3.oas.models.servers.Server;
import org.springframework.context.annotation.*;

import java.util.List;

@Configuration
public class CustomOpenApiConfig {

    @Bean
    @Primary
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("我的项目 API")
                        .version("2.1.0")
                        .description("交付给客户 A 的内部接口集合")
                        .contact(new Contact().name("张三").email("zhangsan@example.com"))
                        .license(new License().name("Apache 2.0")))
                .servers(List.of(
                        new Server().url("https://api.example.com").description("生产"),
                        new Server().url("https://staging.example.com").description("预发")
                ));
    }
}

@Primary 让 Spring 在冲突时优先选业务方的 Bean。

这是当前的折衷做法

理想方案是把 title / version / servers 抽成 @ConfigurationProperties，让业务方在 application.yml 写而不是写 Java 代码。后续如有需要可以演进，详见设计文档 · 整体架构 · 设计取舍。

Result 包裹机制能不能关掉

可以但需要业务方自己实现：往容器里注入一个 OperationCustomizer Bean，让它的 getOrder() 返回比 Ordered.LOWEST_PRECEDENCE 更高的值，并把响应 schema 还原回原始形态。

更简单的做法是按接口粒度加 @RawResponse，文档与运行时都不被包裹。完整原理见设计文档 · 响应包装定制器。

配置说明 ​

常用 application.yml 配置 ​

springdoc 关键项 ​

knife4j 关键项 ​

覆盖默认 OpenAPI Bean ​