wikiwi/swagger-ui

Swagger UI Docker镜像

镜像概述

Swagger UI Docker镜像提供了在NGINX环境中运行的Swagger UI应用，允许开发团队和终端用户可视化和交互API资源，无需了解实现逻辑。该镜像基于OpenAPI规范（前身为Swagger规范）自动生成可视化文档，便于后端开发和客户端使用。

核心功能与特性

• 自动文档生成：从OpenAPI规范自动生成交互式API文档
• 交互式API测试：支持直接在界面中发送API请求并查看响应
• 多版本兼容：支持不同版本的OpenAPI规范（详见兼容性表格）
• 零依赖部署：通过Docker容器化，简化部署流程，无需手动配置依赖
• 轻量级架构：基于NGINX提供高效的静态资源服务

兼容性

Swagger UI与OpenAPI规范的兼容性如下：

使用场景

• API开发文档：为开发团队提供实时更新的API文档
• API测试工具：允许开发者直接在界面中测试API端点
• API展示平台：向第三方或终端用户展示API功能和使用方法
• 团队协作：作为前后端协作的接口文档，统一API理解

使用方法

基本部署

通过以下命令启动Swagger UI容器：

bash
docker run -p 8080:8080 docker.xuanyuan.run/swaggerapi/swagger-ui

访问 http://localhost:8080 即可查看默认的Swagger UI界面。

指定API文档

如需加载自定义的OpenAPI规范文件，可通过环境变量或挂载文件实现：

通过环境变量指定远程URL

bash
docker run -p 8080:8080 -e URL=https://petstore.swagger.io/v2/swagger.json docker.xuanyuan.run/swaggerapi/swagger-ui

挂载本地OpenAPI文件

bash
docker run -p 8080:8080 -v /local/path/to/swagger.json:/usr/share/nginx/html/swagger.json docker.xuanyuan.run/swaggerapi/swagger-ui

然后访问 http://localhost:8080/?url=swagger.json 查看本地文档。

Docker Compose配置

创建 docker-compose.yml 文件：

yaml
version: '3'
services:
  swagger-ui:
    image: docker.xuanyuan.run/swaggerapi/swagger-ui
    ports:
      - "8080:8080"
    environment:
      - URL=https://petstore.swagger.io/v2/swagger.json
    restart: always

启动服务：

bash
docker-compose up -d

浏览器支持

Swagger UI支持以下浏览器的最新版本：

• Chrome
• Safari
• Firefox
• Edge

已知问题

3.X版本目前存在以下已知问题：

• 仅支持部分历史参数
• 未实现JSON表单编辑器
• 对collectionFormat的支持不完整
• 未实现本地化（翻译）功能
• 不支持外部文件的相对路径引用

安全联系

如发现任何安全相关问题或漏洞，请通过邮件联系 ***，而非使用公共问题跟踪器。