如何在OAS3.0中为Swagger添加openapi.json文件链接（Next.js场景）

针对你用next-swagger-doc生成规范并展示Swagger UI的场景，OAS3.0本身没有专门的内置标签配置这个链接，但可以通过以下几种方式实现，适配你的技术栈：

1. 利用Swagger UI默认行为（最简方案） #

如果你的openapi.json已经部署在可访问的路径（比如/openapi.json），直接在初始化Swagger UI时指定url参数即可。Swagger UI会自动在标题与基础URL下方显示"Download JSON"的链接，无需额外自定义：

// 示例：pages/api-docs.tsx
import { SwaggerUI } from 'next-swagger-doc';

export default function ApiDocs() {
  return (
    <SwaggerUI
      url="/openapi.json" // 直接指向你的JSON文件路径
      customOptions={{
        customSiteTitle: '你的API文档标题',
      }}
    />
  );
}

2. 通过自定义Swagger UI插件添加链接 #

如果需要更灵活的样式或文本，可通过自定义插件在顶部区域插入链接：

import { SwaggerUI } from 'next-swagger-doc';

export default function ApiDocs() {
  const spec = require('../../public/openapi.json');
  return (
    <SwaggerUI
      spec={spec}
      customOptions={{
        plugins: [
          {
            components: {
              Topbar: () => (
                <div style={{ padding: '10px 20px', borderBottom: '1px solid #eee' }}>
                  <a href="/openapi.json" target="_blank" rel="noopener noreferrer">
                    查看完整OpenAPI JSON规范
                  </a>
                </div>
              ),
            },
          },
        ],
      }}
    />
  );
}

3. 结合OAS3.0扩展字段实现 #

先在你的openapi.json的info部分添加自定义扩展字段：

{
  "openapi": "3.0.0",
  "info": {
    "title": "你的API文档",
    "version": "1.0.0",
    "x-openapi-file-url": "/openapi.json"
  },
  // 其他API规范内容
}

再通过Swagger UI插件读取该扩展并渲染链接：

import { SwaggerUI } from 'next-swagger-doc';

export default function ApiDocs() {
  const spec = require('../../public/openapi.json');
  return (
    <SwaggerUI
      spec={spec}
      customOptions={{
        plugins: [
          {
            init: (system) => {
              const openapiUrl = system.getState().spec.json.info['x-openapi-file-url'];
              const originalTopbar = system.getComponent('Topbar');
              // 重写Topbar组件，追加链接
              system.registerComponent('Topbar', () => (
                <>
                  {originalTopbar()}
                  <div style={{ padding: '0 20px 10px', fontSize: '14px' }}>
                    <a href={openapiUrl} target="_blank" rel="noopener noreferrer">
                      下载OpenAPI规范文件
                    </a>
                  </div>
                </>
              ));
            },
          },
        ],
      }}
    />
  );
}

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