shlinkio/shlink-api-spec-ui

Shlink API Spec UI

镜像概述和主要用途

Shlink API Spec UI 是一个基于 Swagger UI 构建的应用程序，专门用于加载和展示 shlink 的 Open API 规范文档。它提供了直观的交互式界面，帮助用户浏览、理解和测试 shlink API。

主要用途：作为 shlink API 的官方文档界面，用于可视化展示 shlink Open API 规范，提供交互式 API 测试环境，支持开发者快速集成和调试 shlink API。

核心功能和特性

• 基于 Swagger UI 构建：利用 Swagger UI 的成熟框架，提供标准化的 API 文档展示能力。
• shlink 规范适配：专门优化以支持 shlink Open API 规范的解析和加载。
• 交互式测试：支持直接在界面输入参数、发送 API 请求并实时查看响应，无需额外工具。
• 可视化文档：结构化呈现 API 端点、参数、响应格式等细节，提升可读性。
• 官方托管版本：提供现成的在线服务（api-spec.shlink.io），无需本地部署即可使用。

使用场景和适用范围

使用场景

• shlink 开发者：查阅 API 文档、调试接口功能。
• 第三方集成者：了解 shlink API 调用方式，验证集成逻辑。
• 学习用户：通过交互式界面快速熟悉 shlink API 的使用方法。

适用范围

所有需要与 shlink API 交互的开发者、集成人员及学习用户。

详细使用方法和配置说明

前提条件

• 已安装 Docker 或 Docker Compose。
• 网络环境可访问 shlink Open API 规范文件（默认或自定义 URL）。

Docker 基本部署

1. 拉取镜像

假设镜像名称为 shlinkio/shlink-api-spec-ui（基于官方 GitHub 仓库推断）：

bash
docker pull shlinkio/shlink-api-spec-ui

2. 启动容器（默认配置）

默认加载官方 shlink API 规范，映射容器 80 端口到主机 8080 端口：

bash
docker run -d -p 8080:80 --name shlink-api-spec-ui shlinkio/shlink-api-spec-ui

启动后，通过浏览器访问 http://<主机IP>:8080 即可打开界面。

自定义配置（环境变量）

可通过环境变量 API_SPEC_URL 指定自定义的 shlink Open API 规范文件 URL（默认加载官方最新规范）：

bash
docker run -d -p 8080:80 \
  -e API_SPEC_URL="https://example.com/custom-shlink-api.yaml" \  # 自定义规范 URL
  --name shlink-api-spec-ui shlinkio/shlink-api-spec-ui

Docker Compose 部署示例

创建 docker-compose.yml 文件：

yaml
version: '3'
services:
  shlink-api-spec-ui:
    image: shlinkio/shlink-api-spec-ui
    ports:
      - "8080:80"  # 主机端口:容器端口（容器内默认使用 80 端口）
    environment:
      - API_SPEC_URL="https://api.shlink.io/v3/openapi.yaml"  # 可选：自定义规范 URL
    container_name: shlink-api-spec-ui
    restart: unless-stopped  # 容器退出时自动重启（可选）

启动服务：

bash
docker-compose up -d

注意事项

• 若未指定 API_SPEC_URL，应用默认加载 shlink 官方最新 API 规范。
• 确保主机映射端口（如示例中的 8080）未被占用，或根据需要修改端口映射（格式：主机端口:80）。
• 官方托管版本（api-spec.shlink.io）可直接访问，适合快速查阅，无需本地部署。