网站导航
> 技术文档 > 5分钟玩转Swagger UI：Docker部署+静态化实战_swaggerui

5分钟玩转Swagger UI：Docker部署+静态化实战_swaggerui

网友: 技术文档 2025-07-30 18:19:49

本文来自「大千AI助手」技术实战系列，专注用真话讲技术，拒绝过度包装。

Swagger UI作为API文档可视化利器，能自动生成交互式文档，大幅提升开发效率。下面分享两种高效部署方案：

为什么需要Swagger UI？

  • • ✅ 自动生成API交互文档

  • • ✅ 支持在线接口调试

  • • ✅ 实时展示API变更

往期文章推荐:

  • 18.记录下blog的成长过程
  • 17.再说一说LangChain Runnable接口
  • 16.Docker实战：5分钟搞定MySQL容器化部署与最佳实践
  • 15.Ollama模板全解析：从基础语法到高级应用实战
  • 14.Ollama完全指南：从零开始玩转本地大模型部署
  • 13.django中如何解析content-type=application/json的请求
  • 12.实测DeepSeek分词机制：你的输入如何变成计费Token？
  • 11.英语分词进化论：BPE相关论文汇总
  • 10.硬核实战 | 3分钟Docker部署ClickHouse列存数据库
  • 9.技术深解 | DeepSeek-R1-0528训练参数全透视：163K上下文与MoE高效架构的基石
  • 8.DeepSeek最新升级实测：推理能力翻倍，但离世界顶尖还有多远？
  • 7.血泪教训！Redis默认配置竟会导致数据丢失？Docker生产部署指南
  • 6.Function Call：大模型如何突破自身局限“使用工具“
  • 5.DeepSeek动手实践：创建一个自动连点器
  • 4.告别无效提示！使用少样本学习让AI秒懂你的需求
  • 3.解密PromptTemplate：为什么说它是AI时代的Jinja模板？
  • 2.LangChain Core架构解析：模块化设计与LCEL原语实现原理
  • 1.拒绝重复造轮子！LangChain如何简化LLM应用开发？

安装

  • • Step1.拉取镜像 - docker pull swaggerapi/swagger-ui

  • • Step2.运行服务

    • • 单个schema(本地schema文件) - docker run -d --name=swaggerapi -p 8080:8080 -e SWAGGER_JSON=/schemas/schema.yaml -v D:/swaggerapi/conf/:/schemas swaggerapi/swagger-ui

    • • 单个schema(远程schema文件)

      • • 方式1 - docker run -d --name=swaggerapi -p 8080:8080 -e SWAGGER_JSON_URL=https://petstore.swagger.io/v2/swagger.json swaggerapi/swagger-ui

      • • 方式2 - docker run -d --name=swaggerapi -p 8080:8080 -e URL=https://petstore.swagger.io/v2/swagger.json swaggerapi/swagger-ui

    • • 多个schema(远程schema文件)

      • • docker run -d --name=swaggerapi -p 8080:8080 -e URLS=\"[{name: \'api-server\', url: \'https://petstore.swagger.io/v2/swagger.json\'}]\" swaggerapi/swagger-ui

配置

配置文件

  • • 按配置展示的为 $SWAGGER_JSON对应的文件

  • • 可按需加载/schemas下的所有文件

设置schema

  • • 单个schema

    • • 使用本地schema文件

      • • 设置环境变量SWAGGER_JSON - docker run ... -e SWAGGER_JSON=... ...

    • • 使用远程schema文件

      • • 方式1.设置环境变量SWAGGER_JSON_URL - docker run ... -e SWAGGER_JSON_URL=... ...

      • • 方式2.设置环境变量URL - docker run ... -e URL=... ...

  • • 多个schema(下拉列表可筛选)

    • • 使用远程schema文件

      • • 设置环境变量URLS - docker run ... -e URLS=... ...

        • • URLS取值为一个列表,每一项为一个对象字典

          • • name为schema的唯一名称(全局唯一)

          • • url为schema的远程地址

        • • 因为是传给docker的环境变量,所以name和url的取值都用单引号引用,URLS取值整体用双引号引用

        • • 如果使用双引号,则需要转义\\\"

        • • 示例: URLS=\"[{name: \'api-user\', url: \'https://petstore.swagger.io/v2/swagger.json\'}]\"

设置服务地址path前缀

  • • 设置环境变量BASE_URL - docker run ... -e BASE_URL=/swagger ...

访问

  • • 客户端 - 浏览器访问地址localhost:8080

静态部署(当作静态文件)

  • • Step1.直接下载https://github.com/swagger-api/swagger-ui/blob/HEAD/dist目录的文件

  • • Step2.将dist目录作为静态文件部署到nginx等上

  • • Step3.修改swagger-initializer.js中的SwaggerUIBundle的配置设置自己的schema文件地址信息

    • • 单个 - 修改url配置项为对应的schema文件地址即可

      • • 示例: url: \"https://petstore.swagger.io/v2/swagger.json\"

    • • 多个筛选 - 增加urls配置像为对应的schema文件地址列表即可,列表的每一项是一个object,name为名称,url为地址

      • • 示例: urls: [{name: \"api-user\", url: \"https://petstore.swagger.io/v2/swagger.json\"}]

  • • Step4.直接访问对应的地址即可

避坑指南

  1. 1. 跨域问题：确保API服务器配置CORS

  2. 2. 鉴权处理：通过requestInterceptor注入Token

requestInterceptor: (req) => {    req.headers.Authorization = \"Bearer xxxxx\"    return req;

本文由「大千AI助手」原创发布，专注用真话讲AI，回归技术本质。拒绝神话或妖魔化。搜索「大千AI助手」关注我，一起撕掉过度包装，学习真实的AI技术！

网络标签：

相关问题