在關於 RAML – RESTful API 建模語言的上一兩篇文章中，我們介紹了基本語法，包括數據類型和 JSON 模式的使用，並展示瞭如何通過將常見模式提取到 資源類型和特質來簡化 RAML 定義。
在本文中，我們將展示 如何將您的 RAML API 定義分解為模塊，通過使用 包含、庫、覆蓋和擴展。
為了本文的目的，我們將重點關注我們 API 中與名為 Foo 的實體類型的部分。
以下是構成我們 API 的資源：
“include” 的作用是模塊化複雜的屬性值，將其放置在外部文件中，從而提高 RAML 規範的模塊化程度。
我們之前的文章簡要介紹了使用“include”時，在指定數據類型和示例，這些示例的屬性值在 API 中被重複使用的情況。
“!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.raml與其將所有“types”、 “resource types” 或 “traits” 分別放在單獨的“include” 文件中，您還可以使用一種特殊類型的“include”——“typed fragments”，將這些構造體分解為多個“include” 文件，為每個“type”、 “resource type” 或 “trait” 指定不同的文件。
您還可以使用“typed fragments” 來定義 “user documentation items”、 “named examples”、 “annotations”、 “libraries”、 “overlays” 和 “extensions”。 我們稍後會介紹“overlays” 和 “extensions” 的用法。
雖然不是必需的，但“typed fragment” 類型的“include” 文件的第一行可能包含以下格式的 RAML 模塊標識符：
#%RAML 1.0 <fragment-type>例如，對於“trait” 的“typed fragment” 文件，第一行可能是：
#%RAML 1.0 Trait如果使用模塊標識符，則文件的內容必須僅包含指定類型的片段的有效 RAML 內容。
讓我們首先看一下 API 中的 “traits” 部分：
traits:
- hasRequestItem:
body:
application/json:
type: <<typeName>>
- hasResponseItem:
responses:
200:
body:
application/json:
type: <<typeName>>
example: !include examples/<<typeName>>.json為了使用“typed fragments” 來模塊化該部分，我們首先將 “traits” 部分重寫如下：
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>>.jsonRAML 庫 可用於模塊化任意數量和組合的 數據類型、安全方案、資源類型、特性 和 註釋。
雖然通常定義在外部文件中，然後作為 包含 引用，但 庫 也可以內聯定義。 包含在外部文件中的 庫 也可以引用其他 庫。
與常規 包含 或 類型片段 不同，包含在外部文件中的 庫 必須聲明正在定義的頂級元素名稱。
讓我們將我們的 特性 部分作為 庫 文件重寫：
#%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>>.json庫 通過頂級 使用 屬性應用，其值為一個或多個對象，其屬性名稱是 庫 名稱，其屬性值構成 庫 的內容。
在我們創建了 庫 的內容後，例如 安全方案、數據類型、資源類型 和 特性，我們可以將 庫 應用到根 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.raml庫 通過連接 庫 名稱、一個點 (.), 和要引用的元素的名稱（例如，數據類型、資源類型、特性等）來引用。
正如我們在之前的文章中所回顧的，我們使用 特性 來重構我們的 資源類型。 下面的示例演示瞭如何將“item” 資源類型 作為 庫，如何在新的 庫 中包含 特性 庫 (如上所示)，以及如何通過前綴 特性 名稱為其 庫 標識符（“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:Unlike
The first line of an overlay or extension file must be formatted as follows:
RAML 1.0 Overlay
And the first line of an overlay file must be formatted similarly:
RAML 1.0 Extension
When using a set of
The motivation behind
A common use case for
#%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.
Here is how we would define a Spanish language overlay for this section:
#%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.
Another common use case for
As you may infer from the name,
An
Below is an
#%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 ]
And here is a Spanish-language
#%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}
It is worth noting here that although we used an
首先，我們展示了 RAML 中 include 功能如何用於將單個、複雜的屬性值重構為可重用外部文件模塊，即 類型片段。 接下來，我們演示瞭如何使用 include 功能將某些元素的集合外部化為可重用的 庫。 最後，我們通過使用 覆蓋 和 擴展，擴展了 API 的行為和非行為方面。
要了解更多關於 RAML 模塊化技術的知識，請訪問 RAML 1.0 規範。
