Swagger UI 中如何直接加载 YAML 格式的 API 规范字符串

在实际开发中，我们经常会遇到需要将 API 规范集成到 Swagger UI 中的场景。标准的做法是通过 URL 直接加载 Swagger 规范文件，但有时会遇到一些特殊情况，比如 API 规范不是通过标准 URL 提供，而是以字符串形式返回的情况。

问题背景

许多现代 API 管理系统会将 Swagger 规范以 YAML 或 JSON 格式存储，并通过 API 端点返回。有时这些端点返回的不是直接的规范文件，而是将规范内容作为字符串嵌入在 JSON 响应中。例如：

{
  "assetId": "some-uuid",
  "assetName": "api-name",
  "specification": "openapi: 3.0.0\ninfo:\n  title: Sample API\n  version: 1.0.0"
}

这种情况下，直接使用 Swagger UI 的标准配置方法会遇到困难，因为 Swagger UI 默认期望的是一个 URL 或已经解析好的规范对象。

解决方案

Swagger UI 的 SwaggerUIBundle 构造函数支持通过 spec 参数直接传入 API 规范对象。这意味着我们可以：

1. 首先从 API 响应中提取出 YAML 格式的规范字符串
2. 使用 YAML 解析器将其转换为 JavaScript 对象
3. 将这个对象传递给 Swagger UI

具体实现步骤

首先需要安装一个 YAML 解析库，如 js-yaml：

npm install js-yaml

然后在代码中可以这样处理：

import SwaggerUIBundle from 'swagger-ui-dist/swagger-ui-bundle';
import * as yaml from 'js-yaml';

// 假设这是从API获取的响应
const apiResponse = {
  assetId: 'some-uuid',
  assetName: 'api-name',
  specification: 'openapi: 3.0.0\ninfo:\n  title: Sample API\n  version: 1.0.0'
};

// 将YAML字符串解析为JS对象
const specObject = yaml.load(apiResponse.specification);

// 初始化Swagger UI
const ui = SwaggerUIBundle({
  spec: specObject,
  dom_id: '#swagger-ui-container'
});

注意事项

1. 安全性考虑：直接从 API 获取并解析 YAML 内容时，要注意防范潜在的注入攻击。js-yaml 提供了安全模式来解析不受信任的内容。

2. 错误处理：YAML 解析可能会失败，应该添加适当的错误处理逻辑。

3. 性能优化：对于大型 API 规范，解析过程可能会影响页面加载性能，可以考虑使用 Web Worker 在后台线程中处理。

替代方案

如果不想引入额外的 YAML 解析库，也可以考虑以下方法：

1. 服务端转换：在中间件服务中将 YAML 转换为 JSON 后再返回给前端。

2. 预解析：如果 API 规范不经常变化，可以在构建时预先解析并保存为 JSON 文件。

3. 浏览器内置方案：现代浏览器支持 TextDecoder API，可以结合一些轻量级解析方案。

总结

通过将 YAML 格式的 API 规范字符串解析为 JavaScript 对象，我们可以灵活地将其加载到 Swagger UI 中。这种方法特别适合那些无法直接提供规范文件 URL 的场景，为 API 文档的集成提供了更大的灵活性。在实际应用中，开发者可以根据项目需求选择最适合的实现方式，同时注意安全性和性能方面的考虑。