OpenAPI 사양

서버가 제공하는 HTTP API 의 모양을 기계 읽기 가능한 문서로 표현하는 표준이 있습니다. OpenAPI Specification (OAS) 입니다. 한 번 잘 적어 두면 문서 페이지·클라이언트 SDK·모킹·계약 테스트가 같은 출처에서 흘러나옵니다.

1. OpenAPI 에 대한 이야기

사건	시기
Swagger 사양 첫 공개 (Wordnik · Tony Tam 등)	2010–2011
2.0 (Swagger 2.0)	2014
OpenAPI Initiative 설립 (Linux Foundation 산하) · 사양 기증	2015–2016
OpenAPI 3.0	2017
OpenAPI 3.1 (JSON Schema 2020-12 정렬)	2021

"Swagger" 는 현재 SmartBear 의 도구 이름 (예: Swagger UI · Swagger Editor) 으로 남았고, 사양 자체는 OpenAPI 라는 이름으로 옮겨갔습니다.

OpenAPI 문서는 YAML 또는 JSON 으로 작성하며 다음을 표현합니다.

• 서버 URL · 인증 방식.
• 경로 (paths) 와 메서드, 파라미터·요청 body·응답 스키마.
• 재사용 가능한 컴포넌트 (components.schemas · parameters · responses · securitySchemes).
• 태그·예시·외부 문서 링크.

3.1 부터는 JSON Schema 2020-12 와 정렬되어 검증 도구의 호환이 좋아졌습니다.

2. 코드에서 자동 생성

여러 프레임워크가 핸들러 시그니처·타입을 분석해 OpenAPI 문서를 자동 생성합니다.

프레임워크 / 도구	메모
FastAPI	핸들러·Pydantic 모델에서 자동 생성. /openapi.json · /docs · /redoc 기본 노출.
springdoc-openapi	Spring Boot 위에서 어노테이션·DTO 로 생성.
NestJS Swagger	데코레이터 + 모듈 등록.
Hono OpenAPI	@hono/zod-openapi 같은 보조로 zod 스키마에서 생성.
drf-spectacular	Django REST framework 의 OpenAPI 생성기.
Goa · Huma	Go 진영의 코드 → 사양 자동화.

자동 생성은 핸들러에서 멀어진 동적 응답을 정확히 표현하지 못할 수 있어 손으로 보완하는 자리가 종종 있습니다.

3. 사양에서 코드 생성

반대로 사양 → 코드도 가능합니다.

• openapi-generator (이전 swagger-codegen 분기, 2018) — 다언어 클라이언트·서버 스텁 생성.
• oazapfts (TS) — 사양 → TS 클라이언트.
• kubb · orval (TS) — 사양 → React Query/Vue Query 훅 생성.
• Connect / gRPC-gateway — 사양 우선 흐름의 다른 변형 (Protobuf 기반).

4. 뷰어와 에디터

도구	메모
Swagger UI	가장 오래된 표준 뷰어. SmartBear.
Redoc	Redocly 의 정적 문서 생성기. 한 페이지 레이아웃.
Scalar	비교적 최근 (2023 경) 의 뷰어. 깔끔한 UI 와 try-it 콘솔.
Stoplight Elements	임베드 가능한 문서 컴포넌트.

뷰어는 사양만 있으면 어디든 붙일 수 있습니다. FastAPI 가 기본으로 노출하는 /docs 는 Swagger UI, /redoc 은 Redoc 입니다.

5. 사양의 다른 후보

• JSON Schema 단독 — 데이터 검증에 집중. HTTP 의미는 직접 보태야 합니다.
• gRPC + Protobuf — RPC 모델 + 바이너리 직렬화. 브라우저 통신은 gRPC-Web · Connect 가 다리.
• GraphQL — 스키마 자체가 쿼리 언어. 클라이언트 주도형 응답.
• AsyncAPI — 메시지 기반 시스템 (Kafka · MQTT · AMQP · WebSocket) 의 사양. OpenAPI 의 메시지 버전이라 부르기도 합니다.
• TypeSpec (Microsoft, 2023) — 코드처럼 적어 OpenAPI · JSON Schema 로 변환.

OpenAPI 는 HTTP REST 에 최적화되어 있고, 메시지·이벤트·실시간에서는 AsyncAPI 가 더 잘 맞을 때가 있습니다.

6. 사양 우선 vs 코드 우선

• 코드 우선 — 코드에서 사양을 자동 생성. 빠른 시작, 코드와의 동기화 자연스러움.
• 사양 우선 — 사양을 먼저 합의 → 서버·클라이언트 양쪽이 사양에서 코드 생성. 팀 간 계약이 명확.

대규모·여러 팀 협업에서는 사양 우선의 가치가 커진다는 의견이 자주 나옵니다.

7. FastAPI 의 자동 생성

별도 작업 없이 핸들러·Pydantic 모델에서 OpenAPI 가 만들어집니다. 메타데이터를 보태는 자리:

app = FastAPI(
    title='My API',
    version='1.2.0',
    openapi_tags=[{'name': 'users', 'description': '...'}],
)

@app.get('/u/{id}', response_model=UserOut, responses={404: {'model': ErrorOut}})
def get_user(id: int): ...

8. 클라이언트 SDK 생성과 정적 문서

타입만 뽑는 가장 가벼운 흐름:

npx openapi-typescript https://api.example.com/openapi.json -o api.d.ts

호출 함수까지 만들고 싶으면 oazapfts · kubb 같은 도구가 있습니다.

Redoc CLI 로 단일 HTML 빌드:

npx @redocly/cli build-docs openapi.yaml -o docs.html

9. 자주 걸리는 자리

버전 혼동 — 3.0 과 3.1 은 JSON Schema 호환성이 다릅니다 (예: nullable 표현). 도구가 어느 버전을 지원하는지 확인합니다.

oneOf/anyOf/allOf 의 의미 — 자동 생성기가 정확히 따라오지 못해 클라이언트 타입이 어색해질 수 있습니다. 가능한 한 명확한 discriminator (discriminator 키워드) 를 둡니다.

인증 스키마 명시 누락 — securitySchemes 와 라우트별 security 가 빠지면 클라이언트 SDK 가 인증 헤더를 만들지 못합니다.

자동 생성 사양 + 수동 편집의 충돌 — 매번 자동 생성으로 덮입니다. 보완은 코드 어노테이션으로 또는 별도 후처리 스크립트로 합니다.

민감 엔드포인트의 노출 — 운영 환경에서 /openapi.json 자체를 공개할지 결정합니다. 내부 전용이면 게이트웨이에서 차단합니다.

하고픈 말

OpenAPI 는 한 번 잘 적어 두면 문서·SDK·모킹이 모두 따라옵니다. FastAPI 처럼 코드에서 자동 생성되는 환경에서는 사양 작성 비용이 거의 없습니다. 외부 노출 API 는 OpenAPI 사양을 권장합니다.

Next

• rest-api-intro
• websocket-sse

OpenAPI Specification · OpenAPI Initiative · Swagger 도구 모음 · Redoc · Redocly CLI · openapi-generator · AsyncAPI · JSON Schema 를 참고합니다.