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

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

- 주소: https://copyandrun.com/blog/openapi-schemathesis-api-fuzz-test/
- 분야: API 보안
- 발행일: 2026-11-02
- 태그: Schemathesis, OpenAPI, FastAPI, API 시험, 입력 검증

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 실행

<!-- files: run_server.sh -->

가상환경을 만들어 세 패키지를 설치합니다. 이후 명령은 이 가상환경을 활성화한 터미널에서 실행합니다.

```bash
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에만 바인딩합니다.

```bash
sh run_server.sh app_v1 18270
sh run_server.sh app_v2 18271
```

## 2. 결함 두 개를 손으로 확인

<!-- files: app_v1.py -->

`app_v1.py`에는 엔드포인트가 둘 있습니다. `/split`은 `total`을 `people`로 나눠 한 사람 몫을 돌려주는데 `people`이 0인지 검사하지 않습니다. `/orders/{order_id}`는 주문을 돌려주며 명세에는 `total`이 정수로 적혀 있지만, 상태가 `shipped`인 주문은 `"8500.00"` 문자열로 내보냅니다. `JSONResponse`를 직접 돌려주면 FastAPI가 `response_model` 검사를 건너뛰기 때문에 이런 불일치가 생깁니다.

```python
@app.get("/split")
def split(total: int, people: int):
    return {"each": total // people}   # people 이 0 이면 ZeroDivisionError
```

```bash
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로 적혀 있는 것을 확인합니다.](https://copyandrun.com/img/openapi-schemathesis-api-fuzz-test/01-two-defects-by-hand.png)

## 3. Schemathesis로 1차 버전 시험

<!-- files: app_v1.py -->

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)가 나오는 것을 확인합니다.](https://copyandrun.com/img/openapi-schemathesis-api-fuzz-test/02-schemathesis-failures-1.png)

```bash
tail -n +75 out1.txt
```

![GET /split에서 total=9223372036854775808, people=0 요청이 500을 일으킨 재현 curl과, 요약에 실패 4건이 나오는 것을 확인합니다.](https://copyandrun.com/img/openapi-schemathesis-api-fuzz-test/03-schemathesis-failures-2.png)

찾은 실패는 네 건입니다.

| 코드 | 의미 | 이 글의 원인 |
|---|---|---|
| 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. 수정: 입력 범위를 명세에 적고, 응답을 명세대로

<!-- files: app_v2.py -->

`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 분기 삭제가 보이는 것을 확인합니다.](https://copyandrun.com/img/openapi-schemathesis-api-fuzz-test/05-diff-v1-v2.png)

## 5. 2차 버전 재시험

<!-- files: app_v2.py -->

```
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로 끝나는 것을 확인합니다.](https://copyandrun.com/img/openapi-schemathesis-api-fuzz-test/04-schemathesis-pass.png)

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

## 자주 막히는 곳

- **주문 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

```python
"""연습용 주문 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

```python
"""연습용 주문 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

```bash
#!/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 두 개로 시험한 것이며, 결과는 케이스 수와 시드에 따라 달라질 수 있습니다.
