OpenAPI 명세
OpenAPI 문서는 API의 경로, 요청, 응답, 인증과 오류 계약을 구조적으로 관리합니다.
만들기 전에
- 사용자와 시스템 흐름
- 요구사항과 권한
- 상태와 예외
- 관련 데이터 구조
- 공통 오류와 인증 원칙
- 버전과 호환성 정책
만들기
웹에서 OpenAPI 문서를 만들거나 Agent에게 요청합니다.
프로젝트 기준, 관련 Diagram과 ERD를 읽고 [기능 범위]의 OpenAPI 초안을 만들어줘.
초안을 바로 구현 기준으로 확정하지 않고 화면, 데이터 구조와 정책을 비교합니다.
읽기와 갱신
Agent는 OpenAPI 원문을 읽고 전체 내용을 갱신할 수 있습니다. 문서를 읽을 때 형식, 명세 버전, 경로 수와 작업 수 같은 구조 정보도 함께 확인할 수 있습니다.
기존 명세가 있다면 같은 API를 새 문서로 중복 생성하지 말고 영향받는 경로를 확인해 갱신합니다.
검토하기
- 실제 사용자 흐름에 필요한 경로가 있는가
- 요청과 응답 필드가 데이터 구조와 맞는가
- 인증과 권한이 분명한가
- 오류와 예외 응답이 정의되어 있는가
- 상태 변경과 멱등성 규칙이 맞는가
- 기존 사용자를 깨뜨리는 변경이 있는가
중요한 계약 변경과 이유는 Markdown에 남기고 구현·테스트 업무는 Kanban에 연결합니다.
다음 단계
원본 자료와 결과 파일을 관리하려면 File 문서를 확인하세요.