OpenAPI 스키마
문서용 OpenAPI JSON으로 클라이언트를 만들고 요청 및 응답 형식을 검사하세요.
공개 문서가 지원하는 엔드포인트와 필요한 스키마만 포함한 JSON을 제공합니다.
문서용 JSON에 포함되는 정보
OpenAPI 스키마에서 현재 문서가 지원하는 플랫폼 API의 HTTP 메서드, 경로, 기본 URL, 인증 방식, 파라미터, 응답 상태와 필드 구조를 확인할 수 있습니다. 개요와 개별 엔드포인트 문서는 각 값의 사용 맥락과 주의사항을 설명합니다.
클라이언트와 타입 생성, 스키마 테스트, Postman 같은 API 도구 가져오기에는 문서용 JSON을 사용합니다. 요청과 응답을 직접 확인하거나 오류를 해결할 때는 API 엔드포인트의 한국어 설명을 함께 확인합니다.
JSON 가져오기
문서가 검증한 JSON은 다음 주소에서 확인할 수 있습니다.
https://docs.platform.letsur.ai/api/platform-openapi파일로 내려받으려면 다음처럼 요청합니다.
curl --output letsur-platform-openapi.json \
'https://docs.platform.letsur.ai/api/platform-openapi'이 JSON은 플랫폼 API의 내부 구현 전체를 공개하지 않습니다. 공개 문서에서 검증한 엔드포인트와 그 응답에 필요한 스키마만 제공합니다. 문서에 없는 경로를 사용할 수 있다고 가정하지 마세요.
도구에 연결할 때
- 클라이언트와 타입을 생성하기 전에 사용하는 도구가 OpenAPI 3.1을 지원하는지 확인합니다.
- Postman이나 API 검사 도구에는 문서용 JSON 주소를 입력하고, 생성된 HTTP 메서드와 기본 URL을 다시 확인합니다.
- 생성 도구나 검사 도구에 실제 관리 API 키를 입력하거나 스키마 파일에 키를 저장하지 않습니다.
- 생성 결과가 개별 엔드포인트 문서와 다르면 문서용 OpenAPI JSON을 다시 내려받아 확인합니다.
업데이트와 검증본
엔드포인트 화면과 JSON에는 현재 문서가 지원하는 스키마만 반영됩니다. 최신 스키마를 확인하지 못하면 마지막으로 검증한 저장본을 표시하고 그 상태를 엔드포인트 문서 상단에 알립니다.
검증본은 빈 문서를 피하기 위한 대체 읽기 경로입니다. 새 엔드포인트나 필드를 자동으로 추가하지 않으며, 지원하지 않는 스키마 구조를 임의로 단순화하지 않습니다.
문서용 JSON에는 실제 관리 API 키, 스페이스 식별자, 사용량, 잔액이나 계정 데이터가 포함되지 않습니다. 외부 도구가 스키마를 저장할 수 있으므로 조직에서 승인한 도구에만 연결하세요.