Midwayjs中如何使用 Scalar 替代 SwaggerUI ???前言大家好，我是 Ranbow 最近刚接触

前言

大家好，我是 Ranbow

最近刚接触 Midwayjs, 组件中有对Swagger一流的支持，想要尝试集成 Scalar 原因：

个人不是很喜欢 SwaggerUI 的样式
不想引入 swagger-ui-dist 包（也可以使用 CDN 方案）
想通过更简单的方式提供鉴权需求

经过调研，其实用上 Scalar 最简单的集成方式就是使用 HTML + JS 渲染

Scalar 与 Midwayjs 集成

首先我们仍然需要使用 swagger组件，不过配置需要略微修改一下，仅提供 Swagger JSON

// config/config.default.ts
import { renderJSON } from '@midwayjs/swagger';


// 伪代码，可自己制定一些基础配置，记住这里的配置都可以使用，我们只是不需要 swagger 的UI

swagger: {
  swaggerPath: "/_doc",
  swaggerUIRender: renderJSON,
  title: 'API 接口文档',
  description: 'xxx 平台',
  version: '1.0.0',
},

选择一个 Controller，给一个访问文档的接口 （由于我们使用接口返回 HTML，所以这个接口你可以加上业务鉴权，也可以避免一些恶意访问🔐）

// 安装 @scalar/types 到 dev 依赖
import type { AnyApiReferenceConfiguration } from '@scalar/types'


// 伪代码，只有接口部分

@Get('/_doc')
async doc() {
  const swagger = this.ctx.app.getConfig('swagger')
  // 从 swagger 配置中获取文档地址
  const url = swagger.swaggerPath
  // swagger 标题
  const title = swagger.title

  // scalar/types 可以提供相关的类型提示
  const data: AnyApiReferenceConfiguration = {
    url: `${url}/index.json`,
    title: "xxx",
    theme: 'kepler',
    favicon: 'https://www.midwayjs.org/img/logo.svg',
    layout: 'modern',
    servers: [
      {
        url: 'http://localhost:7001',
        description: '开发环境',
      },
    ],
    darkMode: true,
    hideDownloadButton: true,
    hideModels: true,
    defaultHttpClient: {
      targetKey: 'node',
      clientKey: 'fetch',
    },
  }

  // 最后使用简单的字符串拼接 HTML
  return `<!doctypehtml>
    <title>${title}</title>
    <meta charset=utf-8>
    <meta content="width=device-width,initial-scale=1" name=viewport>
    <div id=app></div>
    <script src=https://cdn.jsdelivr.net/npm/@scalar/api-reference>
    </script>
    <script>Scalar.createApiReference("#app", ${JSON.stringify(data)})</script>
  `
}

OK 这就好了，接下来你可以访问你的 Scalar 文档了 http://localhost:7001/_doc