Copy & Run

OpenAPI 명세로 API 자동 시험: Schemathesis로 500 오류 찾기

직접 만든 작은 FastAPI 연습용 API에 입력 검증 없는 정수 파라미터와 명세와 다른 응답 형식을 일부러 넣고, Schemathesis가 어떤 입력으로 어떤 실패(500 오류, 응답 스키마 위반, 문서에 없는 상태 코드)를 찾는지 봅니다. 수정한 뒤 같은 명령이 통과하는 과정까지 로컬에서 따라 합니다.

실습 노트 · 2026-11-02 발행 · 10분 · 2026-11 확인

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
이 단계의 파일 내려받기:app_v1.pyapp_v2.pyrun_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
이 단계의 파일 내려받기:run_server.sh

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"}}

people이 0이면 500이 돌아오고, 주문 2번의 total은 문자열인데 명세는 integer로 적혀 있는 것을 확인합니다.
people이 0이면 500이 돌아오고, 주문 2번의 total은 문자열인데 명세는 integer로 적혀 있는 것을 확인합니다.

이 단계의 파일 내려받기:app_v1.py

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

Examples, Coverage, Fuzzing 세 단계가 모두 실패하고, 주문 조회에서 total이 integer가 아니라는 ST108 위반과 문서에 없는 404(ST103)가 나오는 것을 확인합니다.
Examples, Coverage, Fuzzing 세 단계가 모두 실패하고, 주문 조회에서 total이 integer가 아니라는 ST108 위반과 문서에 없는 404(ST103)가 나오는 것을 확인합니다.

tail -n +75 out1.txt

GET /split에서 total=9223372036854775808, people=0 요청이 500을 일으킨 재현 curl과, 요약에 실패 4건이 나오는 것을 확인합니다.
GET /split에서 total=9223372036854775808, people=0 요청이 500을 일으킨 재현 curl과, 요약에 실패 4건이 나오는 것을 확인합니다.

찾은 실패는 네 건입니다.

코드 의미 이 글의 원인
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비트 정수 최댓값을 넘는 값)로 만들어진 것입니다. 명세에 범위가 없으니 어떤 크기의 정수도 합법적인 입력으로 취급해 시험한다는 뜻입니다.

이 단계의 파일 내려받기:app_v1.py

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

1차와 2차의 diff에서 split의 Query 범위 추가, 404 문서화, shipped 분기 삭제가 보이는 것을 확인합니다.
1차와 2차의 diff에서 split의 Query 범위 추가, 404 문서화, shipped 분기 삭제가 보이는 것을 확인합니다.

이 단계의 파일 내려받기:app_v1.pyapp_v2.py

5. 2차 버전 재시험

st run http://127.0.0.1:18271/openapi.json --max-examples 50 --seed 1 --no-color

Examples, Coverage, Fuzzing이 모두 통과하고 152건 생성에 152건 통과, No issues found로 끝나는 것을 확인합니다.
Examples, Coverage, Fuzzing이 모두 통과하고 152건 생성에 152건 통과, No issues found로 끝나는 것을 확인합니다.

통과했다는 것은 이 명세가 허용하는 입력으로 만든 케이스에서 실패가 없었다는 뜻이며, 로직 오류나 권한 문제가 없다는 보증은 아닙니다.

이 단계의 파일 내려받기:app_v2.py

자주 막히는 곳

  • 주문 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
이 단계의 파일 내려받기:app_v1.pyapp_v2.pyrun_server.sh

확인 범위

  • 확인한 것: 위의 모든 명령과 출력은 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

같은 카테고리의 글