AI로 만든 OpenAPI를 스펙브릿지에 가져오는 방법

01. 실제 구현에서 확인한 정보만 준비하세요

AI에 API 문서를 부탁할 때 메서드, 경로, 인증 방식, 요청 필드, 성공·오류 응답을 함께 전달하세요. 정보가 없는 항목을 그럴듯하게 만들어내지 않도록, 확인할 수 없는 내용은 질문하게 하는 것이 좋습니다.

이 실습은 공개용 주문 API 예제로 진행합니다. 실제 고객 데이터, 내부 서버 주소, 토큰은 포함하지 않았으며 example.invalid 주소는 호출 가능한 서버가 아닙니다.

• 실제 코드를 기준으로 필수 여부와 필드 타입 확인
• 성공 응답 외에 검증 실패·인증 실패·조회 실패도 정리
• 외부 AI에 소스코드를 전달하기 전 회사의 보안 정책 확인

02. AI에 OpenAPI 형식으로 요청하세요

아래 프롬프트에 확인된 API 정보를 덧붙이세요. Markdown 설명만 받는 대신 OpenAPI JSON을 요청하면 스펙브릿지의 가져오기 기능을 활용할 수 있습니다. 샘플은 OpenAPI 3.0.3을 사용합니다.

• 결과를 .json 파일로 저장하고 JSON 문법 확인
• path 파라미터와 경로의 {변수명} 일치 확인
• 실제 구현과 다른 필드·상태 코드가 없는지 확인

아래에서 확인된 API 정보를 OpenAPI 3.0.3 JSON으로 작성해줘.

- 메서드, 경로, 요청·응답 필드, 필수 여부, 인증 방식은 제공한 정보만 사용해줘.
- 불명확한 항목은 추측하지 말고 먼저 질문해줘.
- summary와 description은 한국어로 작성하고 tags로 API를 분류해줘.
- 요청 본문, 성공 응답, 오류 응답에 schema와 안전한 example을 넣어줘.
- 외부 $ref 대신 파일 안의 components/schemas를 사용해줘.
- 실제 토큰, 개인정보, 내부 주소를 예시에 넣지 마.
- JSON에는 주석이나 생략 기호를 넣지 마.

확인된 API 정보:
[여기에 승인된 API 정보를 입력]

03. API 문서에서 파일을 가져오세요

로그인한 뒤 문서를 작성할 수 있는 워크스페이스에서 API 문서 메뉴를 엽니다. 탐색 영역의 가져오기를 누르고 OpenAPI 유형을 선택한 뒤 파일 선택으로 orders-openapi.json을 올리세요. 원본 JSON을 직접 붙여넣는 방법도 가능합니다.

샘플을 처음 가져오면 주문 API 카테고리에 GET 주문 상세 조회와 POST 주문 생성, 총 2개 문서가 분석됩니다. 감지된 형식, 문서 수, 요청·응답 필드와 가져오기 경고를 확인한 뒤 문서 2건 반영을 누르세요.

• 새 연습용 워크스페이스에서 먼저 진행
• 기존 명세와 메서드·경로가 같다면 신규·변경 없음·변경 있음·검토 충돌 상태 확인
• 경고가 있거나 예상과 다른 문서가 있으면 반영 전에 원본 수정

04. 사람이 필드와 예제를 확인하세요

가져온 주문 생성 문서에서 customerId, items 배열과 자식 필드 sku·quantity를 확인하세요. 주문 상세 조회에서는 orderId 경로 파라미터, 성공 응답과 404 오류 응답을 확인합니다.

JSON이 유효하다는 것과 API 명세가 정확하다는 것은 다릅니다. 개발자가 실제 구현과 대조해 인증 조건, 배열 구조, 필수 여부, 오류 응답을 확인해야 합니다.

• GET /orders/{orderId}: 경로 변수와 조회 실패 응답
• POST /orders: 중첩 배열, 필수 필드와 검증 실패 응답
• 실제 API를 테스트할 때는 샘플 주소 대신 승인된 테스트 환경 사용

05. 검토한 버전만 배포하고 공유하세요

팀의 검토가 필요한 변경은 변경안에서 수정본을 작성하고 검토 요청을 보냅니다. 변경 검토에서 비교·승인을 마친 뒤, 배포 문서에서 외부에 전달할 버전을 선택해 배포합니다.

사용자나 상대 워크스페이스를 지정해 공유하거나 필요한 문서만 공개 링크로 전달하세요. 실제 고객사에 공유하기 전 샘플 주소와 인증 예시를 운영 기준에 맞게 다시 확인합니다.