Scala Rho生成的Swagger UI BaseLayout无React依赖自定义方案咨询

1. 能否不引入React、直接从后端侧自定义BaseLayout #

首先明确：BaseLayout是Swagger UI前端层内置的React组件，后端仅负责返回静态资源/重定向，无法直接在Scala后端代码中修改BaseLayout的逻辑。
但有不需要引入React的轻量自定义方案，对后端开发者非常友好：

• 你现在用的是webjar托管的Swagger UI静态资源，你可以将对应版本（3.40.0）的Swagger UI静态文件从webjar中解压出来，放到你Scala后端的静态资源服务目录下自行托管
• 直接编辑解压出来的index.html和配套css文件即可完成绝大多数自定义需求：
  • 改颜色：覆盖Swagger UI内置的css类即可，比如修改顶部导航栏颜色只需要加一行自定义样式：

    <style>
      .swagger-ui .topbar { background-color: #2d3748; }
      .swagger-ui .info h1 { color: #2b6cb0; }
    </style>
    

  • 改logo：直接替换index.html中顶部导航栏的img标签的src属性为你的logo地址
  • 改文案：直接修改index.html中对应文本节点，或者通过SwaggerUIBundle初始化参数配置自定义文案
  • 改示例内容：在SwaggerUIBundle的初始化配置中添加example相关参数，或者用插件修改请求响应示例
• 调整你原有的Scala重定向逻辑，将跳转地址从webjar的index.html改成你自行托管的修改后的index.html地址即可，不需要修改任何React代码，修改后的代码示例如下：

  case GET -> Root =>
    implicitly[Applicative[F]].pure(
      Response[F]()
      .withStatus(Status.SeeOther)
      .withHeaders(Location(Uri.fromString(
        s"${你的静态资源服务路径}/swagger-ui/index.html?url=${swaggerApiJsonPath}").right.get)
      )
    )
  

2. 重定向到自有React站点做自定义的操作方案 #

如果你需要更深度的自定义（比如完全重构布局、添加自定义交互模块），可以选择重定向到自有React站点实现，具体操作步骤如下：

前端侧操作 #

• 在你的React项目中安装Swagger UI相关依赖：执行npm install swagger-ui-react swagger-ui-dist
• 新建API文档页组件，引入Swagger UI组件并传入你的后端swagger json地址：

  import SwaggerUI from 'swagger-ui-react'
  import 'swagger-ui-react/swagger-ui.css'
  
  const ApiDocument = () => {
    // 所有Swagger UI配置都可以通过props传入
    return <SwaggerUI 
      url="https://你的后端服务地址/你的swaggerApiJsonPath"
      docExpansion="none"
      defaultModelsExpandDepth={-1}
    />
  }
  

• 按需自定义：需要改样式直接覆盖Swagger UI的css类，需要自定义布局可以传入自定义的layout组件替换默认BaseLayout，需要调整示例内容可以用拦截器或者自定义插件实现

后端侧操作 #

• 修改你原有的重定向逻辑，将跳转地址从原来的webjar路径改成你React站点的API文档页地址即可
• 不需要做额外的swagger npm集成，后端只需要保证原来的swagger json接口可以正常被前端站点跨域访问即可（如果前后端域名不同的话配置下CORS）

方案选择建议 #

如果只是修改颜色、logo、基础文案、示例内容这类需求，优先选择第一种自行托管静态文件的方案，不需要接触任何前端工程化内容，改完直接放到后端静态资源目录就能用，学习成本极低。
如果需要做高度自定义的交互、布局重构，再选择第二种React集成方案。

内容的提问来源于stack exchange，提问作者gorlemZ