API 문서

이 페이지는 모든 Decentraland 서비스에서 OpenAPI 사양을 사용해 API를 문서화하는 표준을 다룹니다.

목표

우리의 API 문서화 방식은 다음을 보장합니다:

• 표준화 - 모든 서비스에서 일관된 OpenAPI 사양

• 자동화 - GitHub Actions를 통한 검증, 번들링, 배포

• 중앙 집중화 - 모든 서비스 문서는 GitBook을 통해 게시됨

• 소유권 - 문서는 각 서비스 저장소에 함께 존재함

• 접근성 - 기여자 친화적이고 최신 상태의 API 레퍼런스

---

저장소 구조

각 서비스 저장소에는 반드시 다음이 포함되어야 합니다: /docs 다음 구조를 가진 디렉터리:

/docs
  openapi.yaml        # 정본 (OpenAPI 3.1)
  openapi.json        # CI에서 Hugo/렌더러용으로 자동 생성됨
  index.html          # 자동 생성된 독립형 문서(선택 사항)

파일 요구사항

openapi.yaml

• 반드시 정본 소스 파일이어야 함

• 반드시 OpenAPI 3.1 사양을 사용

• 선택적으로 서비스 식별용 접두사를 가질 수 있음(예: worlds-openapi.yaml)

• 선택적으로 다음으로 분리할 수 있음 components/ 또는 examples/ 필요한 경우 디렉터리로

openapi.json

• CI/CD 중 자동 생성됨

• Hugo 및 기타 렌더러에서 사용됨

• 수동으로 편집하지 마세요

index.html

• 자동 생성된 독립형 문서

• Redocly로 빌드됨

• GitHub Pages에 배포됨

---

OpenAPI 표준

작성할 때 openapi.yaml일관성과 명확성을 보장하기 위해 다음 규칙을 따르세요.

엔드포인트 요약

반드시 실제 엔드포인트 경로를 반영해야 합니다:

# ✅ 좋음: 명확한 엔드포인트 경로
paths:
  /world/{world_name}/about:
    get:
      summary: /world/{world_name}/about
      description: 특정 월드에 대한 정보를 가져옵니다
      
# ❌ 나쁨: 일반적인 요약
paths:
  /world/{world_name}/about:
    get:
      summary: 월드 정보 가져오기

Operation ID

반드시 전역적으로 고유하도록 서비스 이름을 포함하세요:

# ✅ 좋음: 서비스 접두사가 붙은 operation ID
operationId: worldsContentServer_getWorldAbout

# ✅ 좋음: 또 다른 예
operationId: socialService_getFriends

# ❌ 나쁨: 일반적이며 충돌할 수 있음
operationId: getAbout

명명 규칙: {serviceName}_{operationDescription}

• camelCase를 사용

• 설명적이되 간결하게

• 필요한 경우 HTTP 메서드 맥락을 포함하세요(예: createUser, deleteParcel)

버전 관리

반드시 시맨틱 버전 관리를 사용하세요(MAJOR.MINOR.PATCH)를 info.version:

openapi: 3.1.0
info:
  title: 월드 콘텐츠 서버 API
  version: 1.2.0  # 의미상 버전 관리
  description: Decentraland 월드를 관리하기 위한 API

버전 증가 규칙:

• 메이저: 중단적 변경 사항(호환되지 않는 API 변경)

• 마이너: 새 기능(하위 호환)

• 패치: 버그 수정(하위 호환)

태그 및 그룹화

반드시 관련 엔드포인트를 그룹화하려면 태그를 사용하세요:

tags:
  - name: 월드
    description: 월드 관리 작업
  - name: 배포
    description: 월드 배포 작업
  - name: 상태 확인
    description: 상태 확인 엔드포인트

paths:
  /worlds:
    get:
      tags:
        - 월드
      summary: /worlds
      operationId: worldsContentServer_listWorlds
      
  /worlds/{world_name}/about:
    get:
      tags:
        - 월드
      summary: /worlds/{world_name}/about
      operationId: worldsContentServer_getWorldAbout

작업은 GitBook의 탐색에서 태그별로 그룹화됩니다. 더 나은 구성을 위해 관련 엔드포인트는 같은 태그 아래에 그룹화하세요.

전체 예시

openapi: 3.1.0
info:
  title: 소셜 서비스 API
  version: 2.1.0
  description: Decentraland의 소셜 상호작용을 관리하기 위한 API
  contact:
    name: Decentraland 기여자
    url: https://decentraland.org

servers:
  - url: https://social.decentraland.org
    description: 운영 서버
  - url: https://social.decentraland.zone
    description: 스테이징 서버

tags:
  - name: 친구
    description: 친구 관리
  - name: 차단된 사용자
    description: 사용자 차단 작업

paths:
  /friends:
    get:
      tags:
        - 친구
      summary: /friends
      operationId: socialService_getFriends
      description: 인증된 사용자의 친구 목록을 반환합니다
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: 성공적인 응답
          content:
            application/json:
              schema:
                type: object
                properties:
                  friends:
                    type: array
                    items:
                      $ref: '#/components/schemas/Friend'
        '401':
          description: 인증되지 않음

components:
  schemas:
    Friend:
      type: object
      required:
        - address
        - createdAt
      properties:
        address:
          type: string
          description: 친구의 Ethereum 주소
        createdAt:
          type: string
          format: date-time
          description: 친구 관계가 성립된 시점

---

로컬 개발

로컬에서 문서 미리보기

OpenAPI 문서를 미리 보려면 Redocly CLI를 사용하세요:

# HTML 문서 빌드
yarn redocly build-docs docs/openapi.yaml -o docs/index.html

# 그런 다음 브라우저에서 docs/index.html을 여세요

package.json에 추가

편의를 위해 빌드 스크립트를 추가하세요:

{
  "scripts": {
    "build:api": "redocly bundle docs/openapi.yaml -o docs/openapi.json --ext json && redocly build-docs docs/openapi.yaml -o docs/index.html",
    "preview:api": "redocly preview-docs docs/openapi.yaml"
  }
}

Redocly CLI 설치

# npm 사용
npm install -g @redocly/cli

# yarn 사용
yarn global add @redocly/cli

OpenAPI 사양 검증

# 사양을 검증하세요
redocly lint docs/openapi.yaml

# 번들링 및 검증
redocly bundle docs/openapi.yaml

---

자동화 설정

1단계: GitBook 비밀 정보 구성

API 사양을 GitBook에 게시하려면 저장소에 다음 비밀 정보를 추가하세요:

Settings → Secrets and variables → Actions → New repository secret

비밀 이름	설명	찾을 위치
GITBOOK_ORGANIZATION_ID	GitBook 조직 ID	GitBook Settings → Organization
GITBOOK_TOKEN	GitBook API 토큰	GitBook Settings → API Tokens

이 비밀 정보는 자동화 워크플로가 GitBook에 게시하려면 반드시 구성되어야 합니다.

2단계: GitHub Actions 워크플로 추가

다음 파일을 생성하세요: .github/workflows/build-api-docs.yml 저장소에:

name: build-app-docs

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
  pull_request:
    paths:
      - 'docs/**'

jobs:
  build:
    uses: decentraland/platform-actions/.github/workflows/apps-docs.yml@main
    with:
      api-spec-file: 'docs/openapi.yaml'
      output-file: 'docs/index.html'
      output-directory: './docs'
      api-spec-name: '{service-name}-api'  # 예: 'social-service-api'
      node-version: '20'
    secrets: inherit

매개변수:

• api-spec-file: OpenAPI 사양 경로(일반적으로 docs/openapi.yaml)

• output-file: HTML 문서를 생성할 위치

• output-directory: 출력 파일 디렉터리

• api-spec-name: API 사양의 고유 이름(GitBook에서 사용)

• node-version: 사용할 Node.js 버전

이 워크플로는 다음을 수행합니다:

1. ✅ OpenAPI 사양 검증

2. ✅ 사양을 단일 파일로 번들링

3. ✅ Redocly를 사용해 정적 HTML 문서 생성

4. ✅ GitHub Pages에 자동 배포

5. ✅ (비밀 정보가 구성된 경우) 사양을 GitBook에 게시

3단계: GitHub Pages 활성화

저장소에서 GitHub Pages를 구성하세요:

1. 다음으로 이동: Settings → Pages

2. 다음에서 빌드 및 배포:

   • 설정: 원본 를 GitHub Actions

3. 이름이 다음인 환경이 있는지 확인하세요 github-pages

4. 설정을 저장

첫 번째 성공적인 워크플로 실행 후, 문서는 다음에서 확인할 수 있습니다:

• HTML 문서: https://decentraland.github.io/<repo>/index.html

• OpenAPI 사양: https://decentraland.github.io/<repo>/openapi.yaml

• 번들된 JSON: https://decentraland.github.io/<repo>/openapi.json

이 URL은 저장소가 존재하고 GitHub Pages가 활성화되어 있는 한 유효합니다.

---

GitBook에 추가

API 문서가 배포되면 중앙 집중식 GitBook 문서에 추가하세요.

수동 추가(현재 프로세스)

1. GitBook 스페이스로 이동하세요

2. 다음으로 이동: API 참조 섹션

3. 클릭: Add API Reference

4. 서비스 세부 정보를 입력하세요:

   • 이름: 서비스 이름(예: "Social Service")

   • OpenAPI URL: https://decentraland.github.io/{repo-name}/openapi.yaml

5. 저장

GitBook 통합 기능

GitBook은 자동으로 다음을 수행합니다:

• OpenAPI 사양을 파싱합니다

• 대화형 API 문서를 생성합니다

• 태그를 기반으로 엔드포인트 탐색을 생성합니다

• "Try it" 기능을 제공합니다

• 사양을 업데이트하면 문서도 동기화된 상태로 유지합니다

---

전체 설정 흐름

초기 설정

Unexpected error with integration mermaid: Integration is not installed on this space

지속적인 업데이트

Unexpected error with integration mermaid: Integration is not installed on this space

---

모범 사례

문서 품질

• 설명적으로 작성: 명확한 요약과 설명을 작성하세요

• 예제를 제공: 요청/응답 예제를 포함하세요

• 오류를 문서화: 가능한 모든 오류 응답을 설명하세요

• 컴포넌트 사용: 다음을 통해 스키마를 재사용하세요 $ref 중복을 피하기 위해

• 설명을 추가: 모든 매개변수, 속성, 응답에는 설명이 있어야 합니다

모범 사례 예시

paths:
  /users/{address}/friends:
    get:
      tags:
        - 친구
      summary: /users/{address}/friends
      operationId: socialService_getUserFriends
      description: |
        지정된 사용자의 친구 목록을 페이지네이션하여 가져옵니다.
        친구 주소와 친구 관계가 성립된 시점을 포함한 메타데이터를 반환합니다.
      parameters:
        - name: address
          in: path
          required: true
          사용자의 Ethereum 주소(0x 접두사)
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{40}$'
          example: '0x1234567890abcdef1234567890abcdef12345678'
        - name: limit
          in: query
          반환할 친구의 최대 수(1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: offset
          in: query
          페이지네이션을 위해 건너뛸 친구 수
          schema:
            type: integer
            최소값: 0
            default: 0
      responses:
        '200':
          설명: 친구 목록을 성공적으로 가져왔습니다
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FriendsResponse'
              예시:
                friends:
                  - 주소: '0xabcdef...'
                    생성일시: '2024-01-15T10:30:00Z'
                총계: 42
                오프셋: 0
                한도: 50
        '400':
          설명: 잘못된 주소 형식
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              예시:
                오류: '잘못된 주소 형식'
                코드: 'INVALID_ADDRESS'
        '404':
          설명: 사용자를 찾을 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

스키마 재사용성

components:
  schemas:
    오류:
      type: object
      required:
        - 오류
        - 코드
      properties:
        오류:
          type: string
          설명: 사람이 읽을 수 있는 오류 메시지
        코드:
          type: string
          설명: 기계가 읽을 수 있는 오류 코드
        세부정보:
          type: object
          설명: 추가 오류 상황
          
    PaginatedResponse:
      type: object
      required:
        - 오프셋
        - 한도
        - 총계
      properties:
        오프셋:
          type: integer
          설명: 건너뛴 항목 수
        한도:
          type: integer
          설명: 페이지당 최대 항목 수
        총계:
          type: integer
          설명: 사용 가능한 총 항목 수

보안 스키마

components:
  securitySchemes:
    BearerAuth:
      유형: http
      스킴: bearer
      bearerFormat: JWT
      설명: 인증 엔드포인트에서 얻은 JWT 토큰

보안:
  - BearerAuth: []

---

유효성 검사 및 품질 확인

커밋 전 유효성 검사

커밋 전 훅 또는 CI 검사를 추가하세요:

# .github/workflows/validate-api-spec.yml
이름: API 사양 검증

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm install -g @redocly/cli
      - run: redocly lint docs/openapi.yaml

일반 유효성 검사 규칙

• 모든 경로에 operation ID가 있습니다

• 모든 작업에 태그가 있습니다

• 모든 매개변수에 설명이 있습니다

• 모든 응답이 문서화되어 있습니다

• 예시가 제공됩니다

• 스키마가 올바르게 참조됩니다

---

문제 해결

워크플로 실패

문제: GitHub Actions 워크플로가 실패합니다

해결 방법:

• 검증 오류가 있는지 워크플로 로그를 확인하세요

• 실행 redocly lint docs/openapi.yaml 로컬에서

• 워크플로 구성에서 파일 경로를 확인하세요

• 시크릿이 올바르게 구성되었는지 확인하세요

GitHub Pages가 작동하지 않음

문제: 문서가 GitHub Pages URL에 표시되지 않음

해결 방법:

• 저장소 설정에서 GitHub Pages가 활성화되어 있는지 확인하세요

• 워크플로가 성공적으로 완료되었는지 확인하세요

• GitHub Pages가 업데이트될 때까지 몇 분 기다리세요

• 확인하세요 github-pages 환경이 존재하는지

GitBook이 동기화되지 않음

문제: GitBook에 업데이트된 API 문서가 표시되지 않음

해결 방법:

• GitBook 시크릿이 올바른지 확인하세요

• OpenAPI URL에 접근 가능한지 확인하세요

• GitBook에서 수동으로 새로고침을 트리거하세요

• OpenAPI 사양이 유효한지 확인하세요

---

기존 문서에서 마이그레이션

기존 API 문서가 있다면:

1. OpenAPI로 내보내기: 기존 문서를 OpenAPI 3.1 형식으로 변환

2. 검증: 사용 redocly lint 를 사용해 준수 여부를 확인

3. 워크플로 추가: GitHub Actions 자동화를 설정

4. 테스트: 문서가 빌드되고 올바르게 배포되는지 확인

5. 링크 업데이트: 기존 문서 링크를 새 GitHub Pages URL로 연결

6. 이전 문서 보관: 전환 기간 동안 참고용으로 이전 문서를 보관

---

다음 단계

• 다음을 검토하세요 잘 알려진 구성 요소 API 구현 표준

• 참고 테스트 표준 API 테스트 가이드라인용

• 다음의 기존 API 예제를 살펴보세요 API 참조 섹션

관련 표준

• 종속성 관리 - npm 종속성과 peerDependencies 관리

• 잘 알려진 구성 요소 - 서비스용 WKC 아키텍처

• 테스트 표준 - 서비스 테스트 패턴

리소스

• OpenAPI 사양: spec.openapis.org

• Redocly CLI: redocly.com/docs/cli

• GitBook API 통합: docs.gitbook.com

• Platform Actions 저장소: github.com/decentraland/platform-actions