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

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

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

为什么需要Swagger UI?

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

  • • ✅ 支持在线接口调试

  • • ✅ 实时展示API变更

往期文章推荐:

安装

  • • 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的环境变量,所以nameurl的取值都用单引号引用,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. 跨域问题:确保API服务器配置CORS
    1. 鉴权处理:通过requestInterceptor注入Token

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

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

相关推荐
Android小码家13 分钟前
Vscode + docker + qt 网络监听小工具
vscode·qt·docker
虚伪的空想家31 分钟前
K8S删除命名空间卡住一直Terminating状态
云原生·容器·kubernetes·删除·卡顿·delete·命名空间
衍余未了2 小时前
k8s除了主server服务器可正常使用kubectl命令,其他节点不能使用原因,以及如何在其他k8s节点正常使用kubectl命令??
云原生·容器·kubernetes
Clownseven2 小时前
Mattermost教程:用Docker搭建自己的开源Slack替代品 (团队聊天)
docker·容器·开源
❀͜͡傀儡师2 小时前
Docker部署Drawnix开源白板工具
docker·容器·开源·drawnix
❀͜͡傀儡师2 小时前
Docker部署Lunalytics开源监控工具
docker·容器·开源·lunalytics
To_再飞行2 小时前
K8s 存储配置资源
linux·云原生·容器·kubernetes
XXYBMOOO4 小时前
Qt UDP 通信类详解与实现
开发语言·网络·c++·qt·网络协议·ui·udp
江池俊6 小时前
解锁无限创意:Tldraw+cpolar如何通过内网穿透技术打破空间限制
docker
Honeysea_706 小时前
容器的定义及工作原理
人工智能·深度学习·机器学习·docker·ai·持续部署