在 GitHub Pages 上发布基于 OAS 的 API 文档

发布: 1个月前 (2026年3月16日 GMT+8 06:00)

5 分钟阅读

原文: Dev.to

I’m happy to translate the article for you, but I don’t have direct access to the content at the URL you provided. Could you please paste the text (or the portion you’d like translated) here? Once I have the material, I’ll translate it into Simplified Chinese while preserving the original formatting, markdown, and code blocks.

环境

组件	版本
OS	macOS Sequoia 15.1.1
CPU	Apple M4
Shell	Zsh 5.9
cURL	8.11.1
Docker Desktop	4.37.2
GitHub API	2022‑11‑28

项目结构

├── docker
│   ├── .env
│   └── docker-compose.yml
├── index.html
├── nginx.conf
└── openapi
    └── openapi.yml

仅作示例。

OpenAPI 规范 (`openapi/openapi.yml`)

openapi: 3.0.3
info:
  title: Sample API
  version: 1.0.0
paths:
  /hello:
    get:
      summary: Hello World Request
      responses:
        "200":
          description: OK
          content:
            text/plain:
              schema:
                type: string
                example: "Hello, World!"

大部分内容与此处所写相同。

Swagger UI (`index.html`)

<!DOCTYPE html>
<html>
<head>
  <title>SwaggerUI</title>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
  <script>
    window.onload = () => {
      window.ui = SwaggerUIBundle({
        url: './openapi/openapi.yml',
        dom_id: '#swagger-ui'
      });
    };
  </script>
</body>
</html>

将 URL 更新为相对路径

window.onload = () => {
  window.ui = SwaggerUIBundle({
    // before
    // url: 'https://petstore3.swagger.io/api/v3/openapi.json',
    // after
    url: './openapi/openapi.yml',
  });
};

使用最新的 Swagger UI 版本

(如上所示，添加最新的 Swagger UI 资源。)

Redoc (`redoc.html`)

<!DOCTYPE html>
<html>
<head>
  <title>Redoc</title>
  <style>
    body {
      margin: 0;
      padding: 0;
    }
  </style>
</head>
<body>
  <redoc spec-url="./openapi/openapi.yml"></redoc>
  <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>

将 `spec-url` 更新为相对路径

<redoc spec-url="./openapi/openapi.yml"></redoc>

固定特定的 Redoc 版本（可选）

<script src="https://cdn.redoc.ly/redoc/2.0.0-rc.56/bundles/redoc.standalone.js"></script>

Nginx 配置 (`nginx.conf`)

server {
    listen 80;

    location / {
        root /usr/share/nginx/html;
        index index.html;
    }
}

默认的 HTTP 端口是 80。
Nginx 服务器运行在 Docker 容器中。

Docker Compose (`docker/docker-compose.yml`)

# Set the host port you want Nginx to be reachable on
# e.g. HOST_PORT=8080
# export HOST_PORT=8080   #  **Prerequisite:** A **Personal Access Token (Classic)** with the `repo` scope.

# Fill in your values
PERSONAL_ACCESS_TOKEN=""
OWNER=""
REPO=""
BRANCH=""

1️⃣ 将仓库设为公开（免费计划的 GitHub Pages 必须）

# Option A – set `private` to false
curl -L -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $PERSONAL_ACCESS_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/repos/$OWNER/$REPO" \
  -d '{"private": false}'

# Option B – set visibility to public
curl -L -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $PERSONAL_ACCESS_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/repos/$OWNER/$REPO" \
  -d '{"visibility": "public"}'

2️⃣ 启用 GitHub Pages

curl -L -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $PERSONAL_ACCESS_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/repos/$OWNER/$REPO/pages" \
  -d '{
        "source": {
          "branch": "'"$BRANCH"'",
          "path": "/"
        }
      }'

将 $BRANCH 替换为你希望 GitHub Pages 使用的分支（例如 main 或 gh-pages）。

请求成功后，你的 OpenAPI 预览将公开可访问，地址为：

https://<your-username>.github.io/<repo>/

启用 GitHub Pages

curl -L -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $PERSONAL_ACCESS_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/repos/$OWNER/$REPO/pages" \
  -d "{
        \"build_type\": \"legacy\",
        \"source\": {
          \"branch\": \"$BRANCH\",
          \"path\": \"/\"
        }
      }"

检查构建状态

curl -L -X GET \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $PERSONAL_ACCESS_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/repos/$OWNER/$REPO/pages/builds/latest"

如果 GitHub Pages 已经启用，将返回 409 Conflict 错误。

请求体引用

由于 BRANCH 变量用于指定分支，请求体必须使用 双引号 来表示 JSON。

软引用（双引号 JSON）

BRANCH="main"

curl -L -d "{
        \"build_type\": \"legacy\",
        \"source\": {
          \"branch\": \"$BRANCH\",
          \"path\": \"/\"
        }
      }"

硬引用（单引号 JSON）

curl -L -d '{
        "build_type": "legacy",
        "source": {
          "branch": "main",
          "path": "/"
        }
      }'

两者产生相同的负载；硬引用的版本更易阅读。

检索 GitHub Pages URL

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $PERSONAL_ACCESS_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/repos/$OWNER/$REPO/pages"

响应中包含 html_url 属性，该属性保存已发布站点的 URL。

取消发布 GitHub Pages

curl -L -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $PERSONAL_ACCESS_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/repos/$OWNER/$REPO/pages"

发送与激活站点时相同的请求（但使用 -X DELETE）即可删除已发布的站点。

附加资源

Swagger UI – 交互式 API 文档。
ReDoc – 替代的 API 文档 UI。

Note: 此发布过程不依赖于 OAS 文件的数量。即使 OAS 定义分散在多个文件中，您仍然可以按照相同的步骤发布文档。

在 GitHub Pages 上发布基于 OAS 的 API 文档

环境

项目结构

OpenAPI 规范 (`openapi/openapi.yml`)

Swagger UI (`index.html`)

将 URL 更新为相对路径

使用最新的 Swagger UI 版本

Redoc (`redoc.html`)

将 `spec-url` 更新为相对路径

固定特定的 Redoc 版本（可选）

Nginx 配置 (`nginx.conf`)

Docker Compose (`docker/docker-compose.yml`)

1️⃣ 将仓库设为公开（免费计划的 GitHub Pages 必须）

2️⃣ 启用 GitHub Pages

启用 GitHub Pages

检查构建状态

请求体引用

软引用（双引号 JSON）

硬引用（单引号 JSON）

检索 GitHub Pages URL

取消发布 GitHub Pages

附加资源

相关文章

使用 OpenClaw 项目设置向导进行项目脚手架

TokenGate — 为粗粒度 API 提供细粒度权限

wg-easy vs WireGuard：GUI vs 命令行

我不得不自己构建 Symfony validation bundle，因为没有现有的满足我的需求

环境

项目结构

OpenAPI 规范 (openapi/openapi.yml)

Swagger UI (index.html)

将 URL 更新为相对路径

使用最新的 Swagger UI 版本

Redoc (redoc.html)

将 spec-url 更新为相对路径

固定特定的 Redoc 版本（可选）

Nginx 配置 (nginx.conf)

Docker Compose (docker/docker-compose.yml)

1️⃣ 将仓库设为公开（免费计划的 GitHub Pages 必须）

2️⃣ 启用 GitHub Pages

启用 GitHub Pages

检查构建状态

请求体引用

软引用（双引号 JSON）

硬引用（单引号 JSON）

检索 GitHub Pages URL

取消发布 GitHub Pages

附加资源

相关文章

使用 OpenClaw 项目设置向导进行项目脚手架

TokenGate — 为粗粒度 API 提供细粒度权限

wg-easy vs WireGuard：GUI vs 命令行

我不得不自己构建 Symfony validation bundle，因为没有现有的满足我的需求

OpenAPI 规范 (`openapi/openapi.yml`)

Swagger UI (`index.html`)

Redoc (`redoc.html`)

将 `spec-url` 更新为相对路径

Nginx 配置 (`nginx.conf`)

Docker Compose (`docker/docker-compose.yml`)