OpenAPI(구 Swagger)는 REST API를 기계가 읽을 수 있는 형식으로 정의하는 표준 규격이다. API 문서화, 코드 생성, 테스트 자동화의 기반이 되며 OpenAPI 3.x가 현재 표준이다.
OpenAPI 3.0 스키마
yaml
openapi: "3.0.3"
info:
title: "Blog API"
version: "1.0.0"
paths:
/posts:
get:
summary: 게시물 목록
parameters:
- name: page
in: query
schema: { type: integer, default: 1 }
responses:
"200":
description: 성공
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/Post"
post:
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreatePost"
responses:
"201":
description: 생성됨
components:
schemas:
Post:
type: object
properties:
id: { type: integer }
title: { type: string }
createdAt: { type: string, format: date-time }
CreatePost:
type: object
required: [title, content]
properties:
title: { type: string, maxLength: 200 }
content: { type: string }
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
python
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Post(BaseModel):
title: str
content: str
@app.post("/posts", status_code=201)
async def create_post(post: Post) -> Post:
return post
# /docs, /openapi.json 자동 생성
도구 생태계
| 도구 | 용도 |
|---|
| Swagger UI | 브라우저 기반 API 탐색·테스트 |
| OpenAPI Generator | 클라이언트/서버 코드 자동 생성 |
| Stoplight | API 설계 협업 도구 |
| Redoc | 아름다운 API 문서 생성 |
관련 개념
