Apidog OpenAPI 사양 확장

Apidog는 API 설계 및 관리 기능을 향상시키는 사용자 지정 OpenAPI/Swagger 사양 확장을 지원합니다. 이러한 확장을 사용하면 폴더 구성, 엔드포인트 상태, 유지 관리자 정보와 같은 API 엔드포인트의 추가 메타데이터를 지정할 수 있습니다.

이 참조 가이드에서는 Apidog의 기능과 원활하게 통합하기 위해 OpenAPI/Swagger 사양에서 사용할 수 있는 사용자 지정 x-apidog-* 확장을 문서화합니다.

엔드포인트가 속한 폴더 지정

Apidog는 엔드포인트를 구성할 때 x-apidog-folder 필드를 우선적으로 사용합니다. 이 필드가 존재하지 않으면 tags 필드의 첫 번째 값을 사용합니다.

슬래시 /를 사용하여 다단계 폴더를 구분하십시오. 백슬래시 \와 슬래시 /는 모두 이스케이프가 필요한 특수 문자입니다. 슬래시 / 문자를 나타내려면 \/를 사용하시고, 문자 \를 나타내려면 \\를 사용하십시오.

예시:

"paths": {
  "/pets": {
     "post": {
         ...
         "operationId": "addPet",     
         "x-apidog-folder": "Pet Store/Pet Information"
     }
  }
}

Swagger Annotation 예시:

폴더 구성

설명적인 폴더 이름을 사용하여 엔드포인트를 논리적으로 구성하십시오. 이렇게 하면 탐색이 개선되고 팀 구성원이 엔드포인트를 빠르게 찾는 데 도움이 됩니다.

엔드포인트 상태

x-apidog-status 필드를 사용하여 엔드포인트의 상태를 확인하십시오. 이를 통해 각 API 엔드포인트의 개발 수명 주기를 추적할 수 있습니다.

사용 가능한 상태 값

상태	설명
designing	(설계 중)
pending	(대기 중)
developing	(개발 중)
integrating	(통합 중)
testing	(테스트 중)
tested	(테스트 완료)
released	(릴리스됨)
deprecated	(사용 중단됨)
exception	(예외)
obsolete	(폐기됨)
to be deprecated	(사용 중단 예정)

예시:

"paths": {
    "/pets": {
        "post": {
            ...
            "operationId": "addPet",     
            "x-apidog-status": "released"
        }
    }
}

Swagger Annotation 예시:

상태 추적

엔드포인트 상태는 팀이 개발 작업을 조율하고 어떤 API가 프로덕션 사용 준비가 되었는지 이해하는 데 도움이 됩니다.

유지 관리자

x-apidog-maintainer 필드를 사용하여 엔드포인트의 유지 관리자를 지정하십시오. 해당 값은 팀 내 Apidog 사용자의 닉네임 또는 사용자 이름입니다.

예시:

"paths": {
    "/pets": {
        "post": {
            ...   
            "x-apidog-maintainer": "david"
        }
    }
}

Swagger Annotation 예시:

중요

유지 관리자 값은 올바른 할당을 위해 Apidog에 있는 기존 팀 구성원의 사용자 이름 또는 닉네임과 일치해야 합니다.

Apidog OpenAPI 사양 확장

엔드포인트가 속한 폴더 지정#

엔드포인트 상태#

사용 가능한 상태 값#

유지 관리자#

엔드포인트가 속한 폴더 지정

엔드포인트 상태

사용 가능한 상태 값

유지 관리자