OpenAPI 스펙을 깔끔한 마크다운 문서로 자동으로 변환하는 방법

OpenAPI 파일은 API의 신뢰할 수 있는 소스입니다. 모든 경로, 모든 매개변수, 모든 응답 형식을 나열합니다. 문제는 팀원 중 거의 아무도 원시 YAML이나 JSON을 읽고 싶어 하지 않는다는 것입니다. 백엔드 엔지니어는 저장소에서 빠른 엔드포인트 참조를 원합니다. 프론트엔드 개발자는 풀 리퀘스트에서 스캔할 수 있는 요청 필드 테이블을 원합니다. 기술 문서는 전체 스키마를 다시 입력하지 않고 위키에 붙여넣을 수 있는 것을 원합니다.

마크다운은 그러한 모든 독자에게 적합한 형식입니다. GitHub, Confluence, 정적 사이트 생성기 및 일반 텍스트 편집기에서 렌더링됩니다. 따라서 반복되는 작업은 다음과 같습니다. 이미 존재하는 openapi.yaml을 가져와서 사람들이 실제로 열어보는 깔끔한 마크다운으로 변환하는 것입니다. 수동으로 하는 것은 느리고 누군가 엔드포인트를 추가하는 순간 내용이 달라집니다. 자동으로 하는 것만이 실제 릴리스 주기와 접촉해도 살아남는 유일한 버전입니다.

버튼

굳이 OpenAPI에서 마크다운을 생성하는 이유

OpenAPI 문서는 기계를 위해 만들어졌습니다. 도구는 이를 파싱하여 클라이언트를 생성하고, 계약 테스트를 실행하고, 요청을 유효성 검사하고, 대화형 문서를 렌더링합니다. 이러한 기계 가독성이 핵심이며, 보호할 가치가 있습니다. 사양 자체를 올바르게 유지하는 방법에 대한 복습이 필요하다면, OpenAPI 유효성 검사 도구 가이드는 어떠한 것도 생성하기 전에 린팅하는 방법을 다룹니다.

마크다운은 다른 문제를 해결합니다. OpenAPI 렌더러가 실행되지 않는 곳에서 사람들에게 배포하는 것입니다. 몇 가지 구체적인 사례가 계속해서 반복됩니다.

저장소 내 README.md 또는 /docs 폴더. 새로운 기여자가 코드베이스를 벗어나지 않고 엔드포인트 목록을 볼 수 있습니다.
새로운 엔드포인트가 무엇을 수락하고 반환하는지 보여줘야 하는 풀 리퀘스트 설명.
비엔지니어를 포함한 전체 팀이 계약을 검토하는 Confluence 또는 Notion 페이지.
Docusaurus, MkDocs 또는 Hugo와 같이 마크다운을 입력으로 사용하는 정적 문서 사이트.

핵심 단어는 '자동으로'입니다. 한 번 작성하고 잊어버린 마크다운 파일은 다음 스프린트에서는 틀린 내용이 됩니다. 변경될 때마다 사양에서 재생성된 마크다운 파일은 계약에 무료로 충실하게 유지됩니다. 이것이 사람들이 신뢰하는 문서와 사람들이 무시하게 되는 문서의 차이입니다.

신속한 방법부터 완벽한 방법까지: 변환 방법

OpenAPI와 함께 제공되는 마크다운을 생성하는 단일 공식 명령은 없습니다. 대신 컨버터들의 작은 생태계와 API 플랫폼에 내장된 문서 엔진이 존재합니다. 다음은 각 방법이 필요로 하는 설정량에 따라 대략적으로 정렬된 현황입니다.

방법	최적의 용도	얻게 되는 결과물
`openapi-to-md` / `openapi-markdown`	빠르고 설정이 필요 없는 마크다운 덤프	단일 마크다운 파일 또는 스키마 테이블
Widdershins	코드 탭이 있는 Slate/Docusaurus 스타일 문서	언어 샘플이 포함된 테마 적용 가능한 마크다운
파싱된 사양을 활용한 사용자 지정 스크립트	팀이 원하는 정확한 레이아웃	템플릿화하는 모든 것
Apidog	하나의 작업 공간에서 사양 가져오기, 렌더링된 문서 및 테스트	호스팅된 문서와 마크다운 콘텐츠 블록

필요한 제어 수준과 결과물이 최종적으로 어디에 배치되어야 하는지에 따라 선택하세요. 다음 섹션에서는 각 방법을 실행하는 방법을 보여줍니다.

방법 1: 한 줄짜리 오픈 소스 컨버터

가장 빠른 방법은 전용 컨버터를 사용하는 것입니다. 잘 알려진 두 가지 컨버터는 Node 및 Python 환경을 다룹니다.

Node 프로젝트의 경우, openapi-to-md는 YAML 또는 JSON 형식의 v2 또는 v3 문서를 가져와 구조화된 마크다운 파일을 작성합니다. 전역 설치 없이 실행할 수 있습니다.

npx openapi-to-md openapi.yaml api-reference.md

Python 툴체인의 경우, openapi-markdown은 pip 설치 및 단일 명령으로 동일한 작업을 수행합니다.

pip install openapi-markdown
openapi2markdown openapi.yaml api-reference.md

두 도구 모두 사양을 읽고, 모든 경로와 스키마를 탐색하며, 엔드포인트별 제목과 매개변수 및 응답 테이블이 포함된 하나의 마크다운 파일을 생성합니다. 이러한 도구 중 일부에서는 출력 파일 인수가 선택 사항입니다. 이를 생략하면 입력 이름에 .md 확장자가 붙은 파일이 기본으로 생성됩니다. 이는 필요에 따라 재생성하는 저장소 참조로 충분합니다.

빠른 컨버터의 단점은 레이아웃 제어입니다. 자신의 구조가 아닌 컨버터의 구조를 따르게 됩니다. 기본 테이블이 팀이 문서를 읽는 방식과 일치한다면 한 줄로 끝낼 수 있습니다. 5개 언어로 된 코드 샘플이나 특정 섹션 순서가 필요하다면 다음 방법을 원할 것입니다.

방법 2: 코드 샘플이 포함된 테마 적용 가능한 문서를 위한 Widdershins

Widdershins는 OpenAPI 또는 Swagger 파일을 Slate 호환 마크다운으로 변환하는 데 사용되는 잘 알려진 Node 도구입니다. 언어 코드 탭과 사용자 지정 가능한 템플릿을 원할 때, 그리고 마크다운이 Docusaurus 또는 MkDocs와 같은 정적 사이트 생성기에 공급될 때 선택해야 할 도구입니다.

설치하고 기본적인 변환을 실행하세요:

npm install -g widdershins
widdershins openapi.yaml -o api-reference.md

출력을 자체 프론트 매터 헤더를 추가하는 곳으로 파이프할 때 코드 샘플 언어를 추가하고 프론트 매터 헤더를 제거하세요:

widdershins --language_tabs 'shell:cURL' 'python:Python' 'javascript:JavaScript' \
  --omitHeader openapi.yaml -o api-reference.md

Widdershins는 템플릿 시스템을 사용하므로, 기본값을 수용하는 대신 모든 섹션의 레이아웃을 재정의할 수 있습니다. 이는 원시 덤프와 완전히 수작업으로 구축된 문서 사이트 간의 다리 역할을 합니다. 비용은 이제 템플릿과 빌드 단계를 소유하게 된다는 점인데, 이는 문서 저장소에는 괜찮지만 빠른 README에는 과할 수 있습니다.

방법 3: 정확한 레이아웃이 필요할 때 사용자 지정 스크립트

때로는 기성 컨버터 중 어느 것도 원하는 형태를 만들어내지 못할 수 있습니다. 태그당 하나의 마크다운 파일이 필요하거나, 간결한 엔드포인트 인덱스가 필요하거나, 내부 스타일 가이드에 맞는 스키마 테이블이 필요할 수도 있습니다. 이런 경우, 직접 사양을 파싱하고 출력을 템플릿화하세요. 사양은 그저 구조화된 데이터이므로 생각보다 작업이 적습니다.

모든 작업을 나열하는 최소한의 Node 버전은 다음과 같습니다:

import { readFileSync, writeFileSync } from "node:fs";
import yaml from "js-yaml";

const spec = yaml.load(readFileSync("openapi.yaml", "utf8"));
const lines = [`# ${spec.info.title}`, "", spec.info.description ?? "", ""];

for (const [path, methods] of Object.entries(spec.paths)) {
  for (const [method, op] of Object.entries(methods)) {
    lines.push(`## ${method.toUpperCase()} ${path}`);
    lines.push("");
    lines.push(op.summary ?? "");
    lines.push("");
    const params = op.parameters ?? [];
    if (params.length) {
      lines.push("| Name | In | Required | Description |");
      lines.push("| ---- | -- | -------- | ----------- |");
      for (const p of params) {
        lines.push(`| ${p.name} | ${p.in} | ${p.required ? "yes" : "no"} | ${p.description ?? ""} |`);
      }
      lines.push("");
    }
  }
}

writeFileSync("api-reference.md", lines.join("\n"));

출력에 대한 완벽한 제어를 위해 약 40줄 정도의 코드입니다. 제목, 테이블 열, 파일 분할을 직접 결정합니다. 단점은 유지 보수입니다. 대상 OpenAPI 버전에 기능이 추가되면 스크립트가 이를 학습해야 합니다. 안정적인 내부 스타일의 경우 이러한 절충은 보통 가치가 있습니다. 광범위한 사양 적용 범위를 위해서는 유지 보수되는 컨버터를 사용하는 것이 좋습니다. 이 방법을 스크립트로 만들지 아니면 구매할지 저울질하고 있다면, 마크다운 내보내기 기능을 갖춘 API 문서 생성기에 대한 개요가 유지 보수되는 옵션들을 비교하여 보여줍니다.

방법 4: 사양, 문서, 테스트를 Apidog에 함께 유지하기

위의 컨버터들은 모두 하나의 맹점을 공유합니다. 사양을 마크다운으로 변환한 다음, 둘은 서로 멀어집니다. 누군가 API를 편집하고 컨버터를 다시 실행하는 것을 잊어버리면 마크다운은 거짓말을 하게 됩니다. 해결책은 사양을 홀로 존재하는 파일로 취급하는 것을 멈추고, 문서와 테스트가 함께 업데이트되는 작업 공간의 일부로 취급하는 것입니다.

이것이 Apidog가 사용하는 모델입니다. 기존의 openapi.yaml을 가져오면 Apidog는 모든 경로, 스키마 및 예시를 프로젝트로 읽어들입니다. 거기에서 가져온 사양에서 직접 생성된 렌더링되고 호스팅되는 API 문서를 얻을 수 있으며, 별도의 빌드 단계가 필요 없습니다. 전체 가져오기 흐름은 Swagger 또는 OpenAPI를 가져와 요청을 생성하는 방법에서 다루고 있으며, 사양에서 게시된 참조까지의 경로는 OpenAPI에서 API 문서를 자동 생성하는 방법에서 다룹니다.

두 가지가 이를 일회성 컨버터와 다르게 만듭니다.

첫째, 문서는 사용자 고유의 마크다운 콘텐츠 블록을 지원합니다. 생성된 엔드포인트 참조는 사양에서 가져오며, 시작하기 페이지, 인증 노트, 변경 로그 항목과 같은 수기 마크다운을 그 위에 덧씌울 수 있습니다. Apidog 마크다운으로 문서 작성하기 팁은 이러한 작성 측면을 안내합니다. 따라서 생성된 문서와 작성된 문서 중 하나를 선택하는 것이 아니라, 두 가지를 한 곳에서 얻을 수 있습니다.

둘째, 동일하게 가져온 사양은 테스트 시나리오의 기초가 됩니다. 사양이 정의하는 엔드포인트에 대해 요청과 어설션을 구축한 다음, 이를 실행하여 라이브 API가 문서를 생성한 계약과 여전히 일치하는지 증명합니다. 이렇게 하면 불일치 루프가 닫힙니다. API가 변경되어 계약을 위반하면 테스트가 실패하고, 독자가 알기 전에 문서가 오래되었다는 것을 알 수 있습니다.

따라하려면 Apidog를 다운로드하고, 사양을 가져온 다음, 동일한 프로젝트에서 생성된 문서를 여세요. Apidog가 .md 파일을 디스크에 인쇄한다는 것이 핵심이 아닙니다. 사양, 사람이 읽을 수 있는 문서, 그리고 둘 다 정직하게 유지하는 테스트가 더 이상 세 개의 분리된 파일이 아니게 된다는 점입니다.

자동화하기: CI에서 마크다운 재생성

수동으로 실행하는 컨버터는 잊어버리기 쉽습니다. OpenAPI에서 마크다운을 생성하는 진정한 가치는 변경될 때마다 생성 프로세스가 스스로 실행될 때 발휘됩니다. 패턴은 간단합니다. 사양에 영향을 주는 각 푸시마다 마크다운을 재생성하고 다시 커밋하거나 게시하는 것입니다.

다음은 openapi.yaml이 변경될 때마다 참조를 재생성하는 GitHub Actions 작업입니다:

name: Generate API docs

on:
  push:
    paths:
      - "openapi.yaml"

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - name: Convert spec to Markdown
        run: npx openapi-to-md openapi.yaml docs/api-reference.md
      - name: Commit regenerated docs
        run: |
          git config user.name "docs-bot"
          git config user.email "docs-bot@users.noreply.github.com"
          git add docs/api-reference.md
          git diff --staged --quiet || git commit -m "docs: regenerate API reference"
          git push

이제 마크다운은 사양과 한 커밋 이상 멀어질 수 없습니다. 동일한 아이디어가 GitLab CI 또는 Node나 Python을 사용하는 모든 러너에서 작동합니다. 변환 단계를 widdershins 또는 사용자 스크립트로 바꾸세요.

연결할 가치가 있는 또 다른 부분이 있습니다. 재생성된 문서는 문서가 파생된 사양이 여전히 정확할 때만 신뢰할 수 있습니다. 바로 이 지점에서 명령줄 테스트 실행이 동일한 파이프라인에서 제 역할을 합니다. Apidog CLI는 가져온 사양에 대해 구축한 테스트 시나리오를 단일 명령으로 헤드리스 방식으로 실행합니다:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

어떤 어설션이든 실패하면 0이 아닌 값으로 종료되며, 이는 빌드를 실패시키고 더 이상 그렇게 동작하지 않는 API를 설명하는 문서를 게시하는 것을 막습니다. 전체 플래그 표면은 apidog run 명령 참조에 있으며, 더 광범위한 파이프라인 설정은 Apidog CLI 전체 가이드에 있습니다. 문서 생성과 계약 테스트를 짝지으면 둘이 서로를 강화합니다. 사양은 문서를 생성하고, 테스트는 사양을 증명합니다.

생성된 마크다운 정리하기

생성된 마크다운은 첫 번째 통과에서 완벽한 경우는 거의 없습니다. 몇 가지 습관이 가독성을 유지하는 데 도움이 됩니다.

대상 렌더러가 원하지 않을 경우 자동 생성된 프런트 매터를 제거합니다. Widdershins는 --omitHeader로 이를 수행하며, 다른 도구의 경우 파일 상단에 간단한 sed 명령을 사용합니다.
파일 분할을 결정합니다. 하나의 거대한 마크다운 파일은 README에 적합합니다. 문서 사이트의 경우, 각 페이지가 짧도록 태그 또는 리소스별로 분할합니다.
예시를 현실적으로 유지합니다. 대부분의 컨버터는 사양에서 예시 값을 직접 가져오므로, 생성된 문서의 품질은 OpenAPI의 examples 품질을 따릅니다. 더 나은 예시를 넣으면 더 나은 문서가 나옵니다.
수동으로 편집하지 말고 재생성하세요. 생성된 마크다운을 수동으로 편집하는 순간, 다음 변환 시 덮어쓰게 됩니다. 수기로 작성된 콘텐츠는 별도의 파일에 넣고, 생성기가 참조 섹션만 소유하도록 합니다.

사양 자체가 지저분하다면 소스에서 수정하세요. 더 깔끔한 사양은 더 깔끔한 문서를 만들며, OpenAPI 유효성 검사 도구 게시물은 보기 흉한 출력을 생성하는 공백을 린트하는 방법을 보여줍니다.

팀에 맞는 올바른 방법 선택하기

마크다운이 어디로 가야 하고 얼마나 많은 제어가 필요한지에 따라 도구를 선택하세요.

한 번의 명령으로 저장소 참조를 원하고 레이아웃에 신경 쓰지 않는다면: openapi-to-md 또는 openapi-markdown을 사용하세요.
코드 샘플이 있는 문서 사이트를 구축하고 테마 적용 가능한 템플릿을 원한다면: Widdershins를 사용하세요.
컨버터가 맞출 수 없는 내부 스타일 가이드가 있다면: 파싱된 사양을 활용하여 작은 스크립트를 작성하세요.
문서, 사양, 그리고 이를 정확하게 유지하는 테스트를 별도의 빌드 관리 없이 하나의 작업 공간에 호스팅된 출력으로 함께 유지하고 싶다면: 사양을 Apidog로 가져오세요.

이러한 방법들은 상호 배타적이지 않습니다. 많은 팀들이 Apidog를 사양 및 호스팅된 문서의 신뢰할 수 있는 소스로 사용한 다음, CI에서 컨버터를 실행하여 오프라인 읽기를 위한 마크다운 참조를 저장소에 추가합니다. 사양은 정식으로 유지되며, 마크다운은 언제든지 재생성할 수 있는 파생 아티팩트입니다.

마무리

OpenAPI를 마크다운으로 변환하는 것은 사양을 소스로, 마크다운을 파생 파일로 취급하는 한 해결된 문제입니다. 빠른 저장소 참조를 위해서는 openapi-to-md와 같은 한 줄 컨버터로 충분합니다. 테마 적용 가능한 문서 사이트의 경우 Widdershins가 템플릿과 코드 탭을 제공합니다. 정확한 내부 레이아웃을 위해서는 파싱된 사양을 활용한 짧은 스크립트가 효과적입니다. 그리고 사양, 렌더링된 문서, 그리고 이들을 동기화 상태로 유지하는 테스트를 함께 관리하고 싶다면, Apidog로 가져옴으로써 시간이 지남에 따라 다른 모든 접근 방식을 망가뜨리는 불일치를 제거할 수 있습니다.

무엇을 선택하든 자동화하세요. 사양 변경 시마다 CI에서 마크다운을 생성하면, 팀이 읽는 문서는 항상 설명하는 API와 일치할 것입니다.

버튼