Schemathesis는 OpenAPI 명세를 읽고 명세가 허용하는 입력(과 일부러 벗어난 입력)을 스스로 만들어 API에 보내, 서버가 500을 내거나 응답이 명세와 다른 경우를 찾아 주는 도구입니다. 이 글에서는 연습용 API 하나에서 결함 두 개를 찾고 고친 뒤 같은 명령이 통과하는 것까지 확인합니다.
본인이 만든 로컬 API에만 실행합니다. Schemathesis는 한 번에 수십에서 수백 건의 요청을 보내므로 다른 사람의 서버나 운영 서비스에 쓰면 안 됩니다. 이 글의 모든 요청은 127.0.0.1에서 도는 연습용 서버로만 갑니다. 아래 app_v1.py는 일부러 결함을 넣은 연습용 코드이며 실제 서비스에 그대로 쓰지 않습니다. Windows Git Bash에서 실행했고, Linux와 macOS는 가상환경 활성화 명령만 다릅니다(확인 범위 참고).
준비물
| 항목 | 확인한 값 |
|---|---|
| 실행 환경 | Windows 11, Git Bash, Python 3.12.10 |
| Schemathesis | 4.33.0 (st --version, 명령 이름은 st 와 schemathesis 둘 다 됩니다) |
| FastAPI | 0.162.0 (uvicorn 0.54.0) |
| 포트 | 127.0.0.1의 18270(1차 버전), 18271(2차 버전) |
작업 폴더에는 아래 세 파일을 둡니다. 전체 내용은 글 끝의 ## 전체 코드에 있습니다.
app_v1.py
app_v2.py
run_server.sh
1. 설치와 연습용 API 실행
가상환경을 만들어 세 패키지를 설치합니다. 이후 명령은 이 가상환경을 활성화한 터미널에서 실행합니다.
python -m venv .venv
source .venv/Scripts/activate
pip install schemathesis fastapi uvicorn
st --version
Linux와 macOS는 source .venv/bin/activate입니다. 서버는 터미널 두 개에서 각각 띄우거나 &를 붙여 백그라운드로 실행합니다. run_server.sh는 127.0.0.1에만 바인딩합니다.
sh run_server.sh app_v1 18270
sh run_server.sh app_v2 18271
2. 결함 두 개를 손으로 확인
app_v1.py에는 엔드포인트가 둘 있습니다. /split은 total을 people로 나눠 한 사람 몫을 돌려주는데 people이 0인지 검사하지 않습니다. /orders/{order_id}는 주문을 돌려주며 명세에는 total이 정수로 적혀 있지만, 상태가 shipped인 주문은 "8500.00" 문자열로 내보냅니다. JSONResponse를 직접 돌려주면 FastAPI가 response_model 검사를 건너뛰기 때문에 이런 불일치가 생깁니다.
@app.get("/split")
def split(total: int, people: int):
return {"each": total // people} # people 이 0 이면 ZeroDivisionError
curl -s -w ' [%{http_code}]\n' 'http://127.0.0.1:18270/split?total=10&people=0'
curl -s -w ' [%{http_code}]\n' http://127.0.0.1:18270/orders/2
curl -s http://127.0.0.1:18270/openapi.json | python -c "import json,sys; print(json.dumps(json.load(sys.stdin)['components']['schemas']['Order']['properties']))"
Internal Server Error [500]
{"id":2,"total":"8500.00","status":"shipped"} [200]
{"id": {"type": "integer", "title": "Id"}, "total": {"type": "integer", "title": "Total"}, "status": {"type": "string", "title": "Status"}}

3. Schemathesis로 1차 버전 시험
FastAPI는 /openapi.json으로 명세를 내보냅니다. 이 주소를 그대로 넘기면 됩니다. 이 글에서 쓴 옵션은 --max-examples(퍼징 단계에서 연산당 만들 케이스 수 상한)와 --seed(같은 시드는 같은 케이스를 만듭니다)입니다. 검사 종류는 --checks로 고를 수 있고 기본은 전체입니다. 출력이 길어서 한 번만 실행해 out1.txt에 저장하고, 앞부분과 뒷부분으로 나눠 봅니다. 같은 명령을 두 번 실행하면 케이스 ID가 서로 달라지므로 한 번 저장한 파일을 나눠 보는 쪽이 정확합니다.
st run http://127.0.0.1:18270/openapi.json --max-examples 50 --seed 1 --no-color > out1.txt; head -74 out1.txt

tail -n +75 out1.txt

찾은 실패는 네 건입니다.
| 코드 | 의미 | 이 글의 원인 |
|---|---|---|
| ST101 Server error | 500대 응답 | people=0으로 나누기 오류 |
| ST108 Response violates schema | 응답이 명세와 다름 | total이 문자열 |
| ST103 Undocumented status code | 명세에 없는 상태 코드 | 404(주문 없음)와 500 |
실패마다 Reproduce with: 아래에 curl 명령이 붙으므로 Schemathesis 없이도 같은 요청을 다시 보낼 수 있습니다. 눈여겨볼 점은 people=0과 함께 total이 9223372036854775808(64비트 정수 최댓값을 넘는 값)로 만들어진 것입니다. 명세에 범위가 없으니 어떤 크기의 정수도 합법적인 입력으로 취급해 시험한다는 뜻입니다.
4. 수정: 입력 범위를 명세에 적고, 응답을 명세대로
app_v2.py는 세 가지를 고칩니다. 입력은 Query(ge=1, le=1000)처럼 범위를 선언해 people=0을 422로 거절하고(범위가 OpenAPI 명세에도 적힙니다), 응답은 total을 정수로 돌려줍니다. 없는 주문의 404도 responses에 적어 명세와 실제를 맞춥니다. 본문에서 따로 다루지 않았지만 total에도 ge=0, le=1_000_000_000을 걸었습니다. 3단계에서 total=9223372036854775808 같은 아주 큰 정수가 만들어진 것은 명세에 범위가 없었기 때문이므로, 이 범위는 시험 입력의 크기를 현실적인 값으로 좁히려는 변경입니다.
diff -u app_v1.py app_v2.py

5. 2차 버전 재시험
st run http://127.0.0.1:18271/openapi.json --max-examples 50 --seed 1 --no-color

통과했다는 것은 이 명세가 허용하는 입력으로 만든 케이스에서 실패가 없었다는 뜻이며, 로직 오류나 권한 문제가 없다는 보증은 아닙니다.
자주 막히는 곳
- 주문 2번 응답 위반이 안 잡힙니다. 처음에는
order_id에 예시가 없어 무작위 정수만 보내서 1, 2번 주문을 맞히지 못했습니다.Path(examples=[1, 2])로 예시를 명세에 넣자 Examples 단계에서 잡혔습니다. - 한글 출력이 깨지거나 인코딩 오류가 납니다. Windows에서 출력을 받는 쪽 인코딩 문제였고
export PYTHONUTF8=1로 해결했습니다.
이어서 해 볼 것
--checks not_a_server_error처럼 검사 종류를 줄여 500 오류만 먼저 보기st replay 케이스ID로 실패한 요청 다시 보내기- 이 시험을 CI 단계로 옮겨 PR마다 실행하기
결과 정리
- OpenAPI 명세만 있으면 입력 검증 누락(500)과 명세 불일치를 자동으로 찾을 수 있습니다.
- 범위를 명세에 적으면 입력 검증이 생기고 시험 입력 범위도 함께 좁아집니다.
- 실행은 본인이 만든 로컬 API에만 합니다.
전체 코드
작업 폴더 구조는 아래와 같습니다.
app_v1.py
app_v2.py
run_server.sh
app_v1.py
"""연습용 주문 API 1차 버전입니다. 일부러 결함 두 개를 넣었으므로 실제 서비스에 쓰지 않습니다."""
from fastapi import FastAPI, Path
from fastapi.responses import JSONResponse
from pydantic import BaseModel
app = FastAPI(title="Practice Orders API", version="1.0.0")
ORDERS = {1: {"id": 1, "total": 12000, "status": "paid"},
2: {"id": 2, "total": 8500, "status": "shipped"}}
class Order(BaseModel):
id: int
total: int
status: str
@app.get("/split")
def split(total: int, people: int):
# 결함 1: people 이 0 이어도 막지 않아 ZeroDivisionError 로 500 이 납니다.
return {"each": total // people}
@app.get("/orders/{order_id}", response_model=Order)
def get_order(order_id: int = Path(examples=[1, 2])):
order = ORDERS.get(order_id)
if order is None:
return JSONResponse({"detail": "not found"}, status_code=404)
if order["status"] == "shipped":
# 결함 2: 명세는 total 이 정수인데 문자열로 돌려줍니다.
# JSONResponse 는 response_model 검사를 거치지 않아 그대로 나갑니다.
return JSONResponse({**order, "total": f"{order['total']}.00"})
return order
app_v2.py
"""연습용 주문 API 2차 버전입니다. 1차의 결함 두 개를 고쳤습니다."""
from fastapi import FastAPI, Path, Query
from fastapi.responses import JSONResponse
from pydantic import BaseModel
app = FastAPI(title="Practice Orders API", version="1.0.1")
ORDERS = {1: {"id": 1, "total": 12000, "status": "paid"},
2: {"id": 2, "total": 8500, "status": "shipped"}}
class Order(BaseModel):
id: int
total: int
status: str
@app.get("/split")
def split(total: int = Query(ge=0, le=1_000_000_000),
people: int = Query(ge=1, le=1000)):
# 수정 1: 범위를 명세에 적어 0 은 422 로 거절됩니다.
return {"each": total // people}
@app.get("/orders/{order_id}", response_model=Order,
responses={404: {"description": "없는 주문"}})
def get_order(order_id: int = Path(examples=[1, 2])):
order = ORDERS.get(order_id)
if order is None:
return JSONResponse({"detail": "not found"}, status_code=404)
# 수정 2: 모든 상태에서 명세대로 total 을 정수로 돌려줍니다.
return order
run_server.sh
#!/bin/sh
# 사용: sh run_server.sh app_v1 18270 (127.0.0.1 에만 바인딩합니다)
exec python -m uvicorn "$1:app" --host 127.0.0.1 --port "$2" --log-level warning
확인 범위
- 확인한 것: 위의 모든 명령과 출력은 Windows Git Bash에서 실제로 실행한 결과입니다. 옵션(
--checks,--max-examples,--phases,--seed,--workers)은https://schemathesis.readthedocs.io/en/stable/reference/cli/에서 확인했고, 설치한 4.33.0에서--max-examples,--seed,--no-color,--help의 명령 목록(run, fuzz, replay, explain)을 실행해 확인했습니다. 실패 코드 ST101, ST103, ST108은 출력에 나온 것을 적었습니다. - 하지 못한 것: Linux와 macOS 명령은 실행하지 않았습니다.
--phases,--workers,st replay,st fuzz, 인증이 필요한 API, 상태 기반(stateful) 시험은 실행하지 않았습니다. - 범위의 한계: 연습용 API 두 개로 시험한 것이며, 결과는 케이스 수와 시드에 따라 달라질 수 있습니다.
이 글의 다음 단계
- API 과다 응답 걸러 내기: FastAPI response_model과 응답 필드 점검 게이트저장된 사용자 기록을 그대로 반환하는 연습용 FastAPI 앱에서 해시된 비밀번호, 내부 메모, 다른 사용자의 이메일과 전화번호까지 응답에 나가는 것을 curl로 확인합니다. 응답 모델로 고친 수정판과 비교하고, 허용 필드 목록 대조와 민감 키 이름 탐지를 하는 점검 스크립트를 CI 게이트로 붙입니다.
- API 대량 할당 막기: FastAPI Pydantic extra=forbid요청 JSON을 그대로 사용자 기록에 합치는 연습용 FastAPI 앱에서 일반 사용자가 role을 admin으로 올리는 과정을 curl로 확인합니다. 같은 API를 Pydantic 허용 필드 모델로 고치면 422로 거절되는 것을 비교하고, 회귀를 막는 pytest 게이트를 붙입니다.
이 내용을 팀 교육으로 진행하고 싶으신가요?
인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.
교육 문의하기메일로 보내실 수도 있습니다: fankh111@gmail.com