software

GitHub Pages에 OAS 기반 API 문서 게시

발행: (2026년 3월 16일 AM 07:00 GMT+9)
6 분 소요
원문: Dev.to

I’m happy to translate the article for you, but I don’t have the ability to retrieve the full text from the link you provided. Could you please paste the content you’d like translated (excluding any code blocks or URLs you want to keep unchanged)? Once I have the text, I’ll translate it into Korean while preserving the original formatting and markdown.

환경

구성 요소버전
OSmacOS Sequoia 15.1.1
CPUApple M4
ShellZsh 5.9
cURL8.11.1
Docker Desktop4.37.2
GitHub API2022‑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 Configuration (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 오류가 반환됩니다.

Source: …

요청‑본문 인용

BRANCH 변수를 사용해 브랜치를 지정하기 때문에, 요청 본문에서는 JSON에 double quotes(큰따옴표)를 사용해야 합니다.

소프트 인용 (double‑quoted JSON)

BRANCH="main"

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

하드 인용 (single‑quoted 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 정의가 여러 파일에 걸쳐 분할되어 있더라도, 동일한 단계에 따라 문서를 게시할 수 있습니다.

0 조회
#openapi #swagger-ui #github-pages #docker #nginx #api-documentation #static-site
원문 보기
Share:
Back to Blog

관련 글

더 보기 »