OpenAPI 3.0 스펙 작성 가이드

핵심 내용

• OpenAPI 3.0 스펙을 단순 문서가 아닌 코드 생성, 런타임 검증, 보안 범위 확인에 활용하는 설계 우선 접근 강조
• MSA 환경에서 API가 많아질수록 명확한 스펙, 재사용 가능한 스키마, 일관된 명명 규칙이 중요하다는 점 정리
• OpenAPI Generator의 validate와 generate 명령으로 스펙 검증 및 소스 생성하는 흐름 소개

선택 이유

• 설계 단계부터 모든 엔드포인트에 보안을 고려하는 Security First 권장
• 공통 데이터 모델은 components/schemas로 분리하고 $ref로 재사용해 중복과 혼란을 줄이는 방식 제안

주의할 점

• body 내부에 type: object 같은 인라인 개체 정의를 두지 않고 공유 스키마로 추출할 것
• 배열의 암시적 개체 정의도 피하고 명시적 스키마 참조로 정리할 것
• 스키마 이름과 요소 이름은 Java 생성 코드에 맞게 대문자 시작과 일관된 명명 규칙 유지할 것

적용해볼 점

• OpenAPI Generator로 스펙 유효성 검증 후 코드 생성까지 이어지는 워크플로 구성
• 예제 응답과 보안 스코프를 명시해 소비자와 구현자 모두가 이해하기 쉬운 계약 형태로 관리