이 OpenAPI → Markdown 변환기는 API를 마크다운 표로 정리한 색인을 만듭니다. OpenAPI 3.0·3.1·3.2 파일을 YAML이나 JSON으로 붙여 넣으면 API 제목, 메타데이터 세 줄, 지원하는 오퍼레이션마다 한 행인 표가 나옵니다. 문서 안을 가리키는 $ref 경로 항목은 풀어서 쓰고 웹훅도 표시해 포함합니다.
문서 생성기를 돌리지 않고도 API가 무엇을 제공하는지 짧고 diff하기 좋은 목록이 필요한 README, 위키 페이지, 풀 리퀘스트 설명을 위한 도구입니다. 표가 평범한 마크다운이라 리뷰어는 일반 텍스트 diff에서 변경이 어떤 엔드포인트를 더하거나 빼는지 그대로 볼 수 있습니다.
일부러 전체 레퍼런스가 아니라 색인으로 만들었습니다. 스키마, 파라미터, 응답 본문은 출력하지 않습니다. 변환은 브라우저 안에서 이루어지고 아무것도 업로드되지 않습니다.
사용 방법
OpenAPI 문서 붙여 넣기
OpenAPI 3.0.x, 3.1.x 또는 3.2.x 문서를 YAML이나 JSON으로 2 MiB까지 붙여 넣거나 파일을 편집기에 끌어다 놓습니다. 샘플로 Books API, 참조와 웹훅이 있는 3.1 문서, 문제가 있는 사양을 불러올 수 있습니다.
마크다운 읽기
붙여 넣는 즉시 마크다운이 나타나며
info.title에서 온 1단계 제목으로 시작합니다. 문서를 읽을 수 없으면 편집기 아래 메시지가 이유를 알려 주고 마지막으로 성공한 출력은 그대로 보입니다.표 확인
행은 문서에 나온 순서입니다. 검토 상태는
operationId가 없거나 중복이거나, OpenAPI 3.0에서 응답이 없거나, 경로 파라미터가 없거나 required가 아니라는 뜻입니다. 3.1과 3.2에서 응답이 없으면 참고만 표시하며 준비됨 상태는 유지합니다.복사 또는 다운로드
마크다운을 클립보드로 복사하거나
openapi-index.md로 내려받습니다.읽힐 곳에 붙이기
표를 README, GitHub·GitLab 위키, docs 폴더에 넣으세요. 사양이 바뀔 때마다 다시 변환해 색인을 최신으로 유지하세요.
작동 원리
출력 형식
출력은 고정된 구조입니다. # 제목, OpenAPI 버전·API 버전·서버를 담은 글머리표 목록, 빈 줄, 다섯 열의 GitHub 스타일 파이프 표입니다. 파이프 표는 GitHub Flavored Markdown(GFM 명세)의 일부이며 GitHub, GitLab, 대부분의 위키와 정적 사이트 생성기가 렌더링합니다.
# Demo API
- OpenAPI: 3.0.3
- API version: 1.0.0
- Servers: https://api.example.com
| Method | Path | operationId | Summary | Status |
| --- | --- | --- | --- | --- |
| GET | /books | listBooks | List books | ok |셀 텍스트를 이스케이프하는 방법
파이프 표를 깨뜨릴 수 있는 문자는 이스케이프합니다. 값 속의 |는 \|가 되고, 백슬래시는 두 배로, 값 안의 줄바꿈은 <br>가 됩니다. 제목도 같은 방식으로 이스케이프되어 A | B라는 제목의 API는 # A \| B로 쓰입니다. /pets/{petId} 같은 경로는 표 셀에서 중괄호가 특별하지 않으므로 이스케이프가 필요 없습니다.
요약 열에는 각 오퍼레이션의 요약 텍스트가 들어가며 없으면 대시입니다. 상태 열은 고유한 operationId, 버전별 응답 규칙, 경로의 {name}마다 필요한 in: path 파라미터를 확인해 ok 또는 review로 표시합니다. OpenAPI 3.0은 응답이 필요하지만 3.1과 3.2에서는 없을 때 참고만 표시합니다. 개별 문제는 OpenAPI 뷰어에서 볼 수 있습니다.
나열되는 것
오퍼레이션은 paths의 각 경로 아래 여덟 개의 HTTP 메서드 키(get, post, put, patch, delete, options, head, trace)에서 모읍니다. 같은 문서 안의 $ref 경로 항목은 따라가고, 3.1·3.2 웹훅은 이름 뒤에 (webhook)을 붙입니다. 3.1과 3.2는 components나 webhooks만 있는 문서도 받습니다. 3.2는 3.1처럼 읽으므로 3.2 전용 query와 additionalOperations는 나열하지 않습니다.
실제 예시
openapi: 3.0.3
info:
title: Pet Store
version: 2.1.0
servers:
- url: https://api.example.com/v2
- url: https://staging.example.com/v2
paths:
/pets:
get:
operationId: listPets
summary: List pets
responses:
'200': {description: ok}
post:
operationId: createPet
responses:
'201': {description: created}
/pets/{petId}:
parameters:
- {name: petId, in: path, required: true}
get:
summary: Get one pet
responses:
'200': {description: ok}
delete:
operationId: deletePet
summary: Remove a pet | permanently
responses:
'204': {description: gone}
/health:
head: {}# Pet Store
- OpenAPI: 3.0.3
- API version: 2.1.0
- Servers: https://api.example.com/v2, https://staging.example.com/v2
| Method | Path | operationId | Summary | Status |
| --- | --- | --- | --- | --- |
| GET | /pets | listPets | List pets | ok |
| POST | /pets | createPet | — | ok |
| GET | /pets/{petId} | — | Get one pet | review |
| DELETE | /pets/{petId} | deletePet | Remove a pet \| permanently | ok |
| HEAD | /health | — | — | review |도구의 변환기를 직접 실행한 결과입니다. 마지막 요약 속 파이프는 셀이 나뉘지 않도록 이스케이프됩니다.
openapi: 3.0.3
info:
title: 'A | B'
version: '1'
paths: {}# A \| B
- OpenAPI: 3.0.3
- API version: 1
- Servers: 0
| Method | Path | operationId | Summary | Status |
| --- | --- | --- | --- | --- |오퍼레이션이 없는 API는 머리글과 빈 표를 만듭니다.
openapi: 3.0.3
paths: {}# Untitled API
- OpenAPI: 3.0.3
- API version: —
- Servers: 0
| Method | Path | operationId | Summary | Status |
| --- | --- | --- | --- | --- |제목과 버전은 Untitled API와 대시로 대체됩니다.
자주 하는 실수
출력에 스키마와 파라미터가 있을 것이라 기대
표는 엔드포인트 색인입니다. 요청과 응답을 모두 문서화해야 한다면 문서 생성기를 쓰고 이 색인에서 링크하세요.
여러 파일로 나뉜 사양을 붙여 넣음
$ref: './pets.yaml'만 있는paths항목은 다른 파일을 가리키므로 행이 만들어지지 않습니다. 먼저 파일들을 하나의 문서로 번들링하세요.오래된 표를 커밋
손으로 관리하는 표는 사양과 어긋납니다.
paths가 바뀔 때, 가능하면 같은 풀 리퀘스트에서 다시 생성하세요.ok를 검증 통과로 읽음
상태
ok는operationId, 버전별 응답 규칙, 기본 경로 파라미터 검사를 통과했다는 뜻일 뿐입니다. 사양 전체가 유효하다는 뜻은 아닙니다.좁은 표에 긴 요약
요약 텍스트는 적힌 그대로 표에 들어갑니다. 여러 문장짜리 요약은 행을 넓게 만드니 사양에서 요약은 짧은 한 줄로 유지하세요.
자주 묻는 질문
변환기는 무엇을 출력하나요?
API 제목 제목줄(#), 메타데이터 세 줄, 메서드·경로·operationId·요약 텍스트·상태 표가 있는 마크다운 문서입니다.
설명, 스키마, 예제도 포함하나요?
아니요. 엔드포인트 색인뿐입니다. 파라미터, 요청 본문, 응답, 스키마는 출력하지 않고 오퍼레이션마다 한 줄 요약만 넣습니다.
표가 GitHub에서 제대로 렌더링되나요?
예. GitHub Flavored Markdown의 표준 파이프 표이므로 GitHub, GitLab, 대부분의 위키가 렌더링합니다.
결과를 어떻게 내려받나요?
출력의 다운로드 버튼으로 openapi-index.md를 저장하거나 마크다운을 클립보드로 복사하세요.
어떤 OpenAPI 버전이 되나요?
YAML 또는 JSON으로 된 3.0.x, 3.1.x, 3.2.x입니다. 3.2는 3.1처럼 읽으므로 3.2 전용 query와 additionalOperations는 나열하지 않습니다. Swagger 2.0은 거부됩니다.
$ref를 풀고 웹훅도 포함하나요?
같은 문서 안을 가리키는 경로 항목과 3.1 웹훅((webhook)으로 표시)은 그렇습니다. 다른 파일에 대한 참조는 불러오지 않습니다.
문서가 업로드되나요?
아니요. 변환은 브라우저 안에서 이루어지며 아무것도 서버로 전송되지 않습니다.
더 깊이 읽기
마지막 업데이트: