1. 소개
여기에서 RAML(RESTful API 모델링 언어) 시리즈의 네 번째 기사인 어노테이션 을 사용 하여 RAML API 사양에 대한 사용자 지정 속성을 정의 하는 방법을 보여줍니다 . 이 프로세스는 사양의 메타데이터 확장이라고도 합니다.
공식 언어의 범위를 벗어나는 추가 사양이 필요한 RAML 처리 도구에 대한 후크를 제공하기 위해 어노테이션 을 사용할 수 있습니다.
2. 어노테이션 유형 선언
최상위 annotationTypes 속성 을 사용하여 하나 이상의 어노테이션 유형 을 선언할 수 있습니다.
가장 간단한 경우에는 어노테이션 유형 이름 만 지정하면 됩니다. 이 경우 어노테이션 유형 값 은 암시적으로 문자열로 정의됩니다.
annotationTypes:
simpleImplicitStringValueType:이는 여기에 표시된 보다 명시적인 어노테이션 유형 정의와 동일합니다.
annotationTypes:
simpleExplicitStringValueType:
type: string다른 경우에는 어노테이션 유형 사양에 어노테이션 유형 선언 으로 간주되는 값 개체가 포함됩니다 .
이러한 경우 어노테이션 유형 은 두 가지 선택적 속성이 추가된 데이터 유형과 동일한 구문 을 사용하여 정의됩니다 . 적용 및 allowMultiple 은 어노테이션 이 단일 대상 내에서 두 번 이상 적용될 수 있는지 여부를 나타내는 부울 값 입니다(기본값은 false ).
다음은 추가 속성 및 특성을 포함 하는 어노테이션 유형 을 선언하는 간단한 예입니다 .
annotationTypes:
complexValueType:
allowMultiple: true
properties:
prop1: integer
prop2: string
prop3: boolean2.1. 어노테이션 사용을 지원하는 대상 위치
어노테이션은 API 자체의 루트 수준, 리소스 유형 , 특성 , 데이터 유형 , 문서 항목 , Security 체계 , 라이브러리 , 오버레이 , 확장 및 기타 어노테이션 유형 을 포함하여 여러 루트 수준 대상 위치에 적용(사용)될 수 있습니다 .
어노테이션은 Security 체계 설정 , 리소스 , 메서드 , 응답 선언, 요청 본문 , Response body 및 명명된 예제 에도 적용될 수 있습니다 .
2.2. 어노테이션 유형의 대상 제한
어노테이션 유형 을 하나 이상의 특정 대상 위치 유형으로 제한하려면 allowedTargets 속성을 정의합니다.
어노테이션 유형 을 단일 대상 위치 유형으로 제한할 때 allowedTargets 속성에 해당 대상 위치 유형을 나타내는 문자열 값을 할당합니다.
annotationTypes:
supportsOnlyOneTargetLocationType:
allowedTargets: TypeDeclaration어노테이션 유형 에 대해 여러 대상 위치 유형을 허용하려면 다음과 같이 해당 대상 위치 유형을 나타내는 문자열 값의 배열을 allowedTargets 속성에 할당합니다 .
annotationTypes:
supportsMultipleTargetLocationTypes:
allowedTargets: [ Library, Overlay, Extension ]allowedTargets 속성이 어노테이션 유형 에 정의되지 않은 경우 기본적으로 해당 어노테이션 유형 은 지원 대상 위치 유형에 적용될 수 있습니다.
3. 어노테이션 유형 적용
RAML API 사양의 루트 수준에서 어노테이션 유형 을 정의한 후에는 의도한 대상 위치에 어노테이션 유형을 적용하여 각 인스턴스에 해당 속성 값을 제공합니다. 목표 위치 내 어노테이션 유형 의 적용은 단순히 해당 목표 위치에 대한 어노테이션 이라고 합니다 .
3.1. 통사론
어노테이션 유형 을 적용하기 위해서는 괄호()로 묶인 어노테이션 유형 이름 을 대상 위치의 속성으로 추가 하고 해당 대상에 대해 어노테이션 유형 이 사용할 어노테이션 유형 값 속성을 제공합니다 . 어노테이션 유형 이 RAML 라이브러리 에 있는 경우 라이브러리 참조 와 점(.), 어노테이션 유형 이름을 연결합니다.
3.2. 예시
다음은 위의 코드 스니펫에 나열된 일부 어노테이션 유형 을 API의 다양한 리소스 및 메서드 에 적용하는 방법을 보여주는 예입니다 .
/foos:
type: myResourceTypes.collection
(simpleImplicitStringValueType): alpha
...
get:
(simpleExplicitStringValueType): beta
...
/{fooId}:
type: myResourceTypes.item
(complexValueType):
prop1: 4
prop2: testing
prop3: true4. 사용 사례
어노테이션 의 잠재적 사용 사례 중 하나 는 API에 대한 테스트 사례를 정의하고 구성하는 것입니다.
어노테이션 을 기반으로 API에 대한 일련의 테스트를 생성할 수 있는 RAML 처리 도구를 개발하고 싶다고 가정합니다 . 다음 어노테이션 유형 을 정의할 수 있습니다 .
annotationTypes:
testCase:
allowedTargets: [ Method ]
allowMultiple: true
usage: |
Use this annotation to declare a test case.
You may apply this annotation multiple times per location.
properties:
scenario: string
setupScript?: string[]
testScript: string[]
expectedOutput?: string
cleanupScript?: string[]그런 다음 다음과 같이 어노테이션 을 적용하여 /foos 리소스에 대한 일련의 테스트 사례를 구성할 수 있습니다.
/foos:
type: myResourceTypes.collection
get:
(testCase):
scenario: No Foos
setupScript: deleteAllFoosIfAny
testScript: getAllFoos
expectedOutput: ""
(testCase):
scenario: One Foo
setupScript: [ deleteAllFoosIfAny, addInputFoos ]
testScript: getAllFoos
expectedOutput: '[ { "id": 999, "name": Joe } ]'
cleanupScript: deleteInputFoos
(testCase):
scenario: Multiple Foos
setupScript: [ deleteAllFoosIfAny, addInputFoos ]
testScript: getAllFoos
expectedOutput: '[ { "id": 998, "name": "Bob" }, { "id": 999, "name": "Joe" } ]'
cleanupScript: deleteInputFoos
5. 결론
이 사용방법(예제)에서는 어노테이션 이라는 사용자 지정 속성을 사용하여 RAML API 사양에 대한 메타데이터를 확장하는 방법을 보여주었습니다 .
먼저 최상위 annotationTypes 속성을 사용하여 어노테이션 유형 을 선언하는 방법을 보여주고 적용이 허용되는 대상 위치 유형을 열거했습니다.
다음으로 API에서 어노테이션 을 적용하는 방법을 시연 하고 주어진 어노테이션 을 적용할 수 있는 대상 위치 유형을 제한하는 방법에 대해 설명했습니다.
마지막으로 테스트 생성 도구에서 잠재적으로 지원할 수 있는 어노테이션 유형 을 정의하고 이러한 어노테이션 을 API에 적용하는 방법을 보여줌으로써 잠재적 사용 사례를 소개했습니다.
RAML에서 어노테이션 사용에 대한 자세한 내용은 RAML 1.0 사양 을 참조하십시오 .
github 프로젝트 에서 이 예제에 사용된 API 정의의 전체 구현을 볼 수 있습니다 .
