4.3. 추가 OAS 사양 정보

설명서를 OAS Petstore 문서처럼 표시하려면 관련 Petstore swagger.json 파일과 같은 Swagger 호환 사양을 생성해야 합니다. 즉시 사용 가능한 이 사양을 사용하여 ActiveDocs를 테스트할 수 있습니다. 그러나 이것은 API가 아닙니다.

OAS는 JSON으로 인코딩된 해시에 매핑되는 리소스 선언을 사용합니다. Petstore swagger.json 파일을 예제로 사용하고 각 오브젝트에 대해 알아봅니다.

OAS 개체

API 사양의 루트 문서 오브젝트입니다. 모든 최상위 필드를 나열합니다.

info 오브젝트

info 오브젝트는 API에 대한 메타데이터를 제공합니다. 이 내용은 ActiveDocs 페이지에 나와 있습니다.

경로 오브젝트

paths 오브젝트에는 개별 엔드포인트에 대한 상대 경로가 포함됩니다. 전체 URL을 구성하기 위해 경로가 basePath에 추가됩니다. 경로 는 ACL(액세스 제어 목록) 제약 조건으로 인해 비어 있을 수 있습니다.

오브젝트가 아닌 매개변수는 기본 데이터 유형을 사용합니다. Swagger에서 기본 데이터 유형은 JSON-Schema Draft 4 에서 지원하는 유형을 기반으로 합니다. 추가 기본 데이터 유형 파일이 있지만 3scale은 API 엔드포인트에 CORS가 활성화된 경우에만 사용합니다. CORS를 활성화하면 업로드가 거부되는 api-docs 게이트웨이를 통과하지 않습니다.

현재 OAS는 다음과 같은 dataTypes 를 지원합니다 :

  • int32 및 int64 형식이 가능한 정수입니다. 두 형식 모두 서명됩니다.
  • 가능한 형식이 있는 번호: floating 및 double
  • 일반 문자열
  • 가능한 형식이 있는 문자열: byte, date, date-time, password 및 바이너리
  • boolean