NextDoc4j

主题

NextDoc4j 品牌配置 ​

通过品牌定制功能，您可以轻松自定义文档界面的外观，包括 Logo、标题和动态页脚，打造企业专属的统一文档门户。

品牌配置项速查 ​

品牌定制参数统一挂载在 nextdoc4j.extension.brand 路径下：

参数类型说明示例值
logostring自定义 Logo 路径，支持 classpath 资源引用。classpath:brand/logo/logo.png
titlestring系统主标题，渲染在认证登录页与文档导航顶部。"企业级开放平台 API 文档"
footer-textstring页脚版权说明，支持标准 Markdown 语法与动态环境变量。"Copyright © 2025 [官网](https://...)"

完整配置示例 ​

brand
nextdoc4j:
  extension:
    enabled: true
    brand:
      # 1. 自定义 Logo 文件（推荐放置于 resources/brand/logo/ 目录下）
      logo: classpath:brand/logo/logo.png

      # 2. 自定义系统标题（覆盖 SpringDoc 默认标题）
      title: "星瀚云微服务开放平台 API 文档"

      # 3. 自定义页脚（支持 Markdown 超链接与应用上下文动态变量）
      footer-text: 'Copyright © 2025 [星瀚云科技](https://example.com) ⋅ [${application.name}](${application.url}) v${application.version}'

Logo 资源配置规范 ​

Logo 会自适应深浅主题与 Retina 高清屏，推荐遵循以下工程目录规范：

src/main/resources/
└── brand/
    └── logo/
        └── logo.png    # 建议比例 3:1 ~ 4:1，高度 40px~60px，透明背景 PNG/SVG

系统标题与优先级机制 ​

NextDoc4j 按照以下级联规则智能解析页面主标题：

1
品牌自定义标题（最高优先级）

在 nextdoc4j.extension.brand.title 中声明的定制文本，将全局覆盖其他标题设置。

2
SpringDoc OpenAPI Info 标题（次级优先级）

若未配置品牌标题，系统自动提取 @OpenAPIDefinition(info = @Info(title = '...')) 中的标题。

3
NextDoc4j 默认兜底标题（最低优先级）

若前两者均未设置，系统自动兜底呈现为「NextDoc4j API 文档」。

页脚动态变量与 Markdown 支持 ​

页脚不仅支持 Markdown 超链接语法，还可动态插值 Spring Boot 应用环境信息：

变量占位符取值来源说明示例值
${application.name}spring.application.namestar-user-service
${application.version}项目构建版本或 OpenAPI Version1.4.1
${application.contact.name}OpenAPI Contact 联系人姓名平台架构组
${application.contact.url}OpenAPI Contact 联系网址https://github.com/team
${application.url}应用官网 URLhttps://example.com

页脚模板示例 ​

带链接的版权信息

yaml
footer-text: 'Copyright © 2025 [星瀚云科技](https://example.com)'

完整动态信息展示

yaml
footer-text: 'Copyright © 2025 [${application.contact.name}](${application.contact.url}) ⋅ [${application.name}](${application.url}) v${application.version}'

界面视觉呈现效果 ​

认证登录页品牌展示
认证登录页品牌展示
自定义 Logo 与系统标题无缝呈现于安全登录页头部
文档主页顶部与页脚展示
文档主页顶部与页脚展示
主工作台顶部展示定制 Logo，底部动态渲染环境与版权信息