1. 소개
RAML(RESTful API 모델링 언어)에 대한 처음 두 기사에서 데이터 유형 및 JSON 스키마 사용을 포함한 몇 가지 기본 구문을 소개했으며 일반적인 패턴을 리소스 유형 및 특성 으로 추출하여 RAML 정의를 단순화하는 방법을 보여주었습니다 .
이 기사에서는 포함 , 라이브러리 , 오버레이 및 확장 을 사용 하여 RAML API 정의를 모듈로 분할하는 방법을 보여줍니다 .
2. 우리의 API
이 기사의 목적을 위해 Foo 라는 엔터티 유형과 관련된 API 부분에 초점을 맞출 것입니다 .
API를 구성하는 리소스는 다음과 같습니다.
- GET /api/v1/foos
- POST /api/v1/foos
- GET /api/v1/foos/{fooId}
- PUT /api/v1/foos/{fooId}
- 삭제 /api/v1/foos/{fooId}
3. 포함
포함 의 목적은 속성 값을 외부 파일에 배치하여 RAML 정의에서 복잡한 속성 값을 모듈화하는 것입니다.
첫 번째 기사에서는 속성이 API 전체에서 인라인으로 반복되는 데이터 유형 및 예제를 지정할 때 포함 사용에 대해 간략하게 다루었습니다 .
3.1. 일반 사용법 및 구문
!include 태그 는 속성 값을 포함하는 외부 파일의 위치라는 단일 인수를 사용합니다. 이 위치는 절대 URL, 루트 RAML 파일에 대한 상대 경로 또는 포함 파일에 대한 상대 경로일 수 있습니다.
슬래시(/)로 시작하는 위치는 루트 RAML 파일의 위치에 대한 상대 경로를 나타내며, 슬래시 없이 시작하는 위치는 포함 파일의 위치에 대한 상대 경로로 해석됩니다.
후자에 대한 논리적 귀결은 포함된 파일 자체에 다른 !include 지시문이 포함될 수 있다는 것입니다.
다음은 !include 태그 의 세 가지 사용을 모두 보여주는 예입니다 .
#%RAML 1.0
title: Baeldung Foo REST Services API
...
types: !include /types/allDataTypes.raml
resourceTypes: !include allResourceTypes.raml
traits: !include http://foo.com/docs/allTraits.raml3.2. 입력된 조각
모든 유형 , 리소스 유형 또는 특성 을 각각의 포함 파일에 배치하는 대신 유형이 지정된 조각 으로 알려진 특수 유형의 포함 을 사용 하여 각 구성을 여러 포함 파일로 나누고 각 유형 , 리소스 에 대해 서로 다른 파일을 지정할 수 있습니다. 유형 또는 특성 .
유형이 지정된 조각 을 사용하여 사용자 문서 항목 , 명명된 예제 , 어노테이션 , 라이브러리 , 오버레이 및 확장 을 정의 할 수도 있습니다 . 이 기사의 뒷부분에서 오버레이 및 확장 기능 의 사용에 대해 다룰 것입니다 .
필수는 아니지만 입력된 조각인 포함 파일의 첫 번째 줄은 다음 형식 의 RAML 조각 식별자일 수 있습니다.
#%RAML 1.0 <fragment-type>예를 들어, 특성 에 대해 입력된 조각 파일 의 첫 번째 줄은 다음과 같습니다.
#%RAML 1.0 Trait프래그먼트 식별자가 사용되는 경우 파일의 내용에는 지정되는 프래그먼트 유형에 유효한 RAML만 포함되어야 합니다.
먼저 API 의 특성 섹션 일부를 살펴보겠습니다 .
traits:
- hasRequestItem:
body:
application/json:
type: <<typeName>>
- hasResponseItem:
responses:
200:
body:
application/json:
type: <<typeName>>
example: !include examples/<<typeName>>.jsontyped fragments 를 사용하여 이 섹션을 모듈화하기 위해 먼저 특성 섹션을 다음과 같이 다시 작성합니다.
traits:
- hasRequestItem: !include traits/hasRequestItem.raml
- hasResponseItem: !include traits/hasResponseItem.raml그런 다음 입력된 조각 파일 hasRequestItem.raml 을 작성합니다 .
#%RAML 1.0 Trait
body:
application/json:
type: <<typeName>>입력 된 조각 파일 hasResponseItem.raml 은 다음과 같습니다.
#%RAML 1.0 Trait
responses:
200:
body:
application/json:
type: <<typeName>>
example: !include /examples/<<typeName>>.json4. 도서관
RAML 라이브러리 는 데이터 유형 , Security 체계 , 자원 유형 , 특성 및 어노테이션 의 조합과 수를 모듈화하는 데 사용할 수 있습니다 .
4.1. 라이브러리 정의
일반적으로 외부 파일에 정의되어 포함 으로 참조되지만 라이브러리 는 인라인으로 정의될 수도 있습니다. 외부 파일에 포함된 라이브러리는 다른 라이브러리도 참조 할 수 있습니다 .
일반 include 또는 typed fragment 와 달리 외부 파일에 포함 된 라이브러리 는 정의 중인 최상위 요소 이름을 선언해야 합니다.
특성 섹션을 라이브러리 파일 로 다시 작성해 보겠습니다 .
#%RAML 1.0 Library
# This is the file /libraries/traits.raml
usage: This library defines some basic traits
traits:
hasRequestItem:
usage: Use this trait for resources whose request body is a single item
body:
application/json:
type: <<typeName>>
hasResponseItem:
usage: Use this trait for resources whose response body is a single item
responses:
200:
body:
application/json:
type: <<typeName>>
example: !include /examples/<<typeName>>.json4.2. 라이브러리 적용
라이브러리 는 최상위 용도 속성을 통해 적용되며 속성 이름이 라이브러리 이름이고 속성 값이 라이브러리 의 콘텐츠를 구성 하는 하나 이상의 객체가 값 입니다.
Security 체계 , 데이터 유형 , 리소스 유형 및 특성 에 대한 라이브러리 를 만든 후에는 라이브러리 를 루트 RAML 파일에 적용할 수 있습니다 .
#%RAML 1.0
title: Baeldung Foo REST Services API
uses:
mySecuritySchemes: !include libraries/security.raml
myDataTypes: !include libraries/dataTypes.raml
myResourceTypes: !include libraries/resourceTypes.raml
myTraits: !include libraries/traits.raml4.3. 라이브러리 참조
라이브러리 는 라이브러리 이름, 점(.) 및 참조 되는 요소의 이름(예: 데이터 유형, 리소스 유형, 특성 등)을 연결하여 참조됩니다.
이전 기사 에서 정의한 특성 을 사용하여 자원 유형 을 리팩터링한 방법을 기억할 수 있습니다 . 다음 예는 "항목" 리소스 유형 을 라이브러리 로 다시 작성하는 방법, 새 라이브러리 내에 특성 라이브러리 파일(위에 표시됨) 을 포함하는 방법 및 특성 이름 앞에 라이브러리 이름 한정자 를 추가하여 특성 을 참조하는 방법을 보여줍니다. " myTraits "):
#%RAML 1.0 Library
# This is the file /libraries/resourceTypes.raml
usage: This library defines the resource types for the API
uses:
myTraits: !include traits.raml
resourceTypes:
item:
usage: Use this resourceType to represent any single item
description: A single <<typeName>>
get:
description: Get a <<typeName>> by <<resourcePathName>>
is: [ myTraits.hasResponseItem, myTraits.hasNotFound ]
put:
description: Update a <<typeName>> by <<resourcePathName>>
is: [ myTraits.hasRequestItem, myTraits.hasResponseItem, myTraits.hasNotFound ]
delete:
description: Delete a <<typeName>> by <<resourcePathName>>
is: [ myTraits.hasNotFound ]
responses:
204:5. 오버레이 및 확장
오버레이 및 확장 은 API를 확장하는 데 사용되는 외부 파일에 정의된 모듈입니다. 오버레이 는 설명, 사용 지침 및 사용자 설명서 항목과 같은 API의 비동작 측면을 확장하는 데 사용되는 반면 확장 은 API의 동작 측면을 확장하거나 재정의하는 데 사용됩니다.
다른 RAML 파일이 인라인으로 코딩된 것처럼 적용되도록 참조하는 include 와 달리 모든 오버레이 및 확장 파일 은 마스터 파일에 대한 참조(최상위 masterRef 속성을 통해)를 포함해야 합니다. RAML API 정의 또는 적용할 다른 오버레이 또는 확장 파일.
5.1. 정의
오버레이 또는 확장 파일의 첫 번째 행은 다음과 같은 형식이어야 합니다.
RAML 1.0 Overlay
그리고 오버레이 파일의 첫 번째 줄은 비슷한 형식이어야 합니다.
RAML 1.0 Extension
5.2. 사용 제약
오버레이 및/또는 확장 프로그램 집합을 사용하는 경우 모두 동일한 마스터 RAML 파일을 참조해야 합니다. 또한 RAML 처리 도구는 일반적으로 루트 RAML 파일과 모든 오버레이 및 확장 파일이 공통 파일 확장명(예: ".raml")을 가질 것으로 예상합니다.
5.3. 오버레이 사용 사례
오버레이 이면의 동기 는 구현에서 인터페이스를 분리하는 메커니즘을 제공하여 RAML 정의의 보다 인간 지향적인 부분이 더 자주 변경되거나 증가하는 동시에 API의 핵심 동작 측면은 안정적으로 유지되도록 하는 것입니다.
오버레이 의 일반적인 사용 사례 는 사용자 문서 및 기타 설명 요소를 여러 언어로 제공하는 것입니다. API 제목을 다시 작성하고 일부 사용자 문서 항목을 추가해 보겠습니다.
#%RAML 1.0
title: API for REST Services used in the RAML tutorials on Baeldung.com
documentation:
- title: Overview
- content: |
This document defines the interface for the REST services
used in the popular RAML Tutorial series at Baeldung.com.
- title: Copyright
- content: Copyright 2016 by Baeldung.com. All rights reserved.다음은 이 섹션에 대한 스페인어 오버레이를 정의하는 방법입니다.
#%RAML 1.0 Overlay
# File located at (archivo situado en):
# /overlays/es_ES/documentationItems.raml
masterRef: /api.raml
usage: |
To provide user documentation and other descriptive text in Spanish
(Para proporcionar la documentación del usuario y otro texto descriptivo
en español)
title: |
API para servicios REST utilizados en los tutoriales RAML
en Baeldung.com
documentation:
- title: Descripción general
- content: |
Este documento define la interfaz para los servicios REST
utilizados en la popular serie de RAML Tutorial en Baeldung.com.
- title: Derechos de autor
- content: |
Derechos de autor 2016 por Baeldung.com.
Todos los derechos reservados.오버레이 의 또 다른 일반적인 사용 사례 는 기본적으로 테스트 및 모니터링 도구와 같은 RAML 프로세서에 후크를 제공하기 위해 비표준 구성을 API에 추가하는 방법인 어노테이션 메타데이터 를 외부화 하는 것입니다.
5.4. 확장 사용 사례
이름에서 알 수 있듯이 확장 은 새로운 동작을 추가하거나 API의 기존 동작을 수정하여 API를 확장하는 데 사용됩니다. 객체 지향 프로그래밍 세계의 비유는 하위 클래스가 새 메서드를 추가하거나 기존 메서드를 재정의할 수 있는 상위 클래스를 확장하는 하위 클래스입니다. 확장은 API의 비기능적 측면도 확장할 수 있습니다.
예 를 들어 특정 역할이 할당된 관리자 또는 사용자와 같은 일부 사용자에게만 노출되는 추가 리소스를 정의하기 위해 확장 을 사용할 수 있습니다. 확장 기능 을 사용하여 API의 최신 버전에 대한 기능을 추가할 수도 있습니다.
다음은 API 버전을 재정의하고 이전 버전에서 사용할 수 없었던 리소스를 추가 하는 확장 프로그램 입니다.
#%RAML 1.0 Extension
# File located at:
# /extensions/en_US/additionalResources.raml
masterRef: /api.raml
usage: This extension defines additional resources for version 2 of the API.
version: v2
/foos:
/bar/{barId}:
get:
description: |
Get the foo that is related to the bar having barId = {barId}
typeName: Foo
queryParameters:
barId?: integer
typeName: Foo
is: [ hasResponseItem ]다음은 해당 확장 에 대한 스페인어 오버레이 입니다 .
#%RAML 1.0 Overlay
# Archivo situado en:
# /overlays/es_ES/additionalResources.raml
masterRef: /api.raml
usage: |
Se trata de un español demasiado que describe los recursos adicionales
para la versión 2 del API.
version: v2
/foos:
/bar/{barId}:
get:
description: |
Obtener el foo que se relaciona con el bar tomando barId = {barId}API의 동작을 수정하지 않기 때문에 이 예제에서 스페인어 재정의에 오버레이 를 사용했지만 이 모듈을 확장 으로 쉽게 정의할 수 있다는 점에 주목할 가치가 있습니다 . 그리고 그것 의 목적이 그 위에 있는 영어 확장 에서 발견된 속성을 재정의하는 것이라면 그것은 확장 으로 더 적절하게 정의될 수 있습니다 .
6. 결론
이 사용방법(예제)에서는 일반적인 구성을 외부 파일로 분리하여 RAML API 정의를 보다 모듈화하는 몇 가지 기술을 소개했습니다.
먼저, 우리는 RAML의 포함 기능을 사용하여 개별적이고 복잡한 속성 값을 typed fragments 로 알려진 재사용 가능한 외부 파일 모듈로 리팩토링 하는 방법을 보여주었습니다 . 다음으로 포함 기능을 사용하여 특정 요소 세트를 재사용 가능한 라이브러리 로 외부화 하는 방법을 시연했습니다 . 마지막으로 오버레이 및 확장 을 사용하여 API의 일부 동작 및 비동작 측면을 확장 했습니다.
RAML 모듈화 기술에 대해 자세히 알아보려면 RAML 1.0 사양 을 방문하십시오 .
github 프로젝트 에서 이 예제에 사용된 API 정의 의 전체 구현 을 볼 수 있습니다 .
