API·Swagger 명세 체크리스트 | 직장인 역량노트

설계 전 확인

코드를 쓰기 전에 프론트와 백엔드가 합의해야 하는 최소 항목입니다.

누가 이 API를 호출하는지 명확히 적었다

필요한 화면 또는 사용자 행동을 기준으로 요청/응답을 정의했다

리소스 이름을 복수형 명사로 정리했다

목록 API에 페이지네이션 또는 cursor 기준을 포함했다

인증이 필요한 API와 공개 API를 구분했다

REST 설계 확인

URL, HTTP 메서드, 상태 코드가 같은 기준으로 쓰이는지 점검합니다.

URL에 get, create, update 같은 동사를 넣지 않았다

GET, POST, PUT, PATCH, DELETE의 의미를 구분했다

생성 성공은 201, 요청 오류는 400, 인증 오류는 401, 권한 오류는 403, 없음은 404를 고려했다

성공 응답과 실패 응답의 공통 포맷을 정했다

필드 이름과 타입이 API마다 흔들리지 않는다

OpenAPI 작성 확인

Swagger UI에 표시되는 문서가 실제 계약으로 쓸 수 있는지 확인합니다.

paths에 주요 엔드포인트와 메서드를 정의했다

components/schemas에 재사용할 모델을 분리했다

필수 path/query/body 파라미터를 누락하지 않았다

대표 성공 응답과 대표 에러 응답을 함께 적었다

JWT, API Key 등 인증 방식을 securitySchemes에 적었다

변경 관리 확인

운영 중 API 변경이 기존 클라이언트를 깨뜨리지 않게 관리합니다.

필드 삭제, 타입 변경, 필수 여부 변경을 Breaking Change로 검토했다

스펙 변경을 PR에서 리뷰한다

info.version 또는 changelog에 변경 내용을 남긴다

Swagger UI URL과 스펙 파일 경로를 팀 문서에 고정했다

스펙과 구현이 어긋나지 않는지 배포 전 확인한다

프로젝트 팀원 사용 확인

API를 소비하는 팀원이 Swagger UI와 스펙을 보고 안전하게 기능을 연결할 수 있는지 점검합니다.

Swagger UI URL과 호출 대상 서버가 개발, 스테이징, 운영 중 어디인지 구분했다

인증이 필요한 API는 Authorize 또는 Authorization 헤더 사용 방법을 확인했다

필수 path/query/body 값과 예시 값을 보고 요청을 만들 수 있다

성공 응답뿐 아니라 400, 401, 403, 404 같은 대표 실패 응답을 확인했다

스펙 변경 PR에서 required, enum, 타입 변경이 연동 코드에 미치는 영향을 확인했다

명령

도구 명령어 예시

OpenAPI 스펙 검증

YAML 문법, 필수 필드, 경로 파라미터 누락처럼 리뷰 전에 잡을 수 있는 오류를 도구로 먼저 확인합니다.

npx @redocly/cli@latest lint openapi.yamlOpenAPI 파일 lint 실행

npx @redocly/cli@latest lint --config redocly.yaml openapi.yaml팀 규칙 파일을 적용해 lint 실행

npx @openapitools/openapi-generator-cli validate -i openapi.yamlOpenAPI Generator 기준으로 스펙 유효성 확인

git diff -- openapi.yaml이번 PR에서 API 계약이 어떻게 바뀌었는지 확인

문서와 실제 응답 확인

Swagger UI URL이 열리는지, 스펙 JSON이 내려오는지, 대표 API 응답이 스펙과 맞는지 직접 확인합니다.

curl -i http://localhost:3000/api-docsSwagger UI 라우트 응답 확인

curl -i http://localhost:3000/openapi.jsonOpenAPI JSON 스펙 제공 여부 확인

curl -i http://localhost:3000/products목록 API의 상태 코드와 응답 헤더 확인

curl -i -H "Authorization: Bearer <token>" http://localhost:3000/products인증이 필요한 API를 토큰 포함으로 확인

클라이언트 코드 생성

스펙이 실제 개발 입력값으로 쓸 수 있는지 타입 또는 SDK 생성을 통해 검증합니다.

npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o generated/clientTypeScript fetch 클라이언트 생성

npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g java -o generated/java-clientJava 클라이언트 생성 예시

git diff -- generated/client스펙 변경이 생성 코드에 미치는 영향 확인

루틴

상황별 실무 루틴

API 변경 PR 전 점검

스펙 파일 변경은 코드 변경처럼 리뷰 대상입니다. PR 전 자동 검증과 diff 확인을 먼저 끝냅니다.

git diff -- openapi.yaml변경된 endpoint, schema, required 필드 확인

npx @redocly/cli@latest lint openapi.yaml문법과 규칙 위반 확인

npx @openapitools/openapi-generator-cli validate -i openapi.yaml생성 도구 기준 유효성 확인

git status스펙, 구현, 테스트 변경이 함께 포함됐는지 확인

Swagger UI가 뜨지만 API가 이상할 때

UI 렌더링과 실제 API 응답은 별개입니다. 스펙 원본과 실제 endpoint를 나눠 확인합니다.

curl -i http://localhost:3000/openapi.json현재 서버가 제공하는 스펙 확인

curl -i http://localhost:3000/products실제 endpoint 상태 코드와 응답 구조 확인

curl -i http://localhost:3000/api-docsSwagger UI 라우트 자체 문제인지 확인

git diff -- openapi.yaml로컬 스펙 변경과 서버 반영 여부 비교

인증 API 문서화 검수

securitySchemes가 빠지면 Swagger UI에서 Authorize 테스트가 어렵습니다. 토큰 없는 호출과 토큰 포함 호출을 함께 봅니다.

curl -i http://localhost:3000/products토큰 없이 호출했을 때 401 또는 403 응답 확인

curl -i -H "Authorization: Bearer <token>" http://localhost:3000/products토큰 포함 호출 성공 여부 확인

git diff -- openapi.yamlsecuritySchemes와 endpoint별 security 적용 여부 확인

프론트 개발용 타입 생성

스펙을 기준으로 클라이언트를 생성해보면 schema 누락, 타입 불일치, 잘못된 required 필드를 빨리 발견할 수 있습니다.

npx @openapitools/openapi-generator-cli validate -i openapi.yaml생성 전 스펙 유효성 확인

npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o generated/client프론트에서 검토할 클라이언트 생성

git diff -- generated/client스펙 변경이 타입과 호출 코드에 미친 영향 확인

운영 기준

생성 코드를 저장소에 커밋할지 여부는 팀 기준에 맞춥니다. 커밋하지 않더라도 PR 검수용으로 생성해볼 수 있습니다.

팀원이 Swagger 보고 기능 연결

기능 구현 전에 문서 URL, 인증 방식, 필수 값, 실제 응답을 확인해 연동 실패를 줄입니다.

curl -i http://localhost:3000/openapi.json현재 서버가 제공하는 스펙 파일 확인

curl -i http://localhost:3000/products공개 API의 상태 코드와 응답 포맷 확인

curl -i -H "Authorization: Bearer <token>" http://localhost:3000/products인증 API의 토큰 포함 호출 확인

git diff -- openapi.yaml이번 변경이 schema와 required 필드에 미치는 영향 확인

운영 기준

쓰기 API는 운영 서버에서 Try it out으로 테스트하지 않습니다. 개발 또는 스테이징 서버인지 먼저 확인합니다.

주의

실무에서 자주 깨지는 지점

문서만 있고 구현이 다름

Swagger UI가 있어도 실제 응답과 다르면 더 위험합니다. 스펙 변경과 구현 변경을 같은 PR 또는 같은 릴리스 단위로 관리해야 합니다.

성공 케이스만 문서화

에러 응답이 없으면 프론트는 실패 상황을 추측해야 합니다. 대표 에러 응답은 최소 하나 이상 문서화합니다.

Breaking Change 무공지

응답 필드 삭제, 타입 변경, 필수 파라미터 추가는 기존 클라이언트를 깨뜨릴 수 있습니다. 버전과 변경 이력을 남깁니다.

인증 방식 누락

securitySchemes가 없으면 Swagger UI에서 인증 API를 제대로 테스트할 수 없습니다. JWT, API Key, Cookie 방식을 명시합니다.

검수 기준

Swagger UI가 보인다는 사실만으로 문서화가 끝난 것은 아닙니다. 실제 응답, 에러 구조, 인증 방식, 변경 이력이 스펙과 일치해야 협업 계약으로 쓸 수 있습니다.

샘플

PR에 남길 API 변경 설명

스펙 변경

GET /v1/products에 cursor 페이지네이션 추가ProductSummary schema에 thumbnailUrl 추가401, 403 에러 응답 구조 명시

검증 항목

기존 클라이언트 호환 여부
Swagger UI 렌더링 여부
실제 API 응답과 스펙 일치 여부
변경 이력과 버전 표기 여부

API 코스 목차로 돌아가기

API 명세 체크리스트