註釋可用於為RAML處理工具提供鈎子，這些工具需要超出官方語言範圍的其他規範。
一個或多個標註類型可以使用頂層annotationTypes屬性進行聲明。
在最簡單的情況下，標註類型名稱就是所需的一切，在這種情況下，標註類型值默認為字符串:
annotationTypes:
simpleImplicitStringValueType:這相當於更明確的標註類型定義，如此處所示:
annotationTypes:
simpleExplicitStringValueType:
type: string在其他情況下，標註類型規範將包含一個值對象，該對象被認為是標註類型聲明。
在這種情況下，標註類型使用與數據類型相同的語法定義，並添加兩個可選屬性：allowedTargets，其值是字符串或字符串數組，限制了標註可以應用的類型位置，以及allowMultiple，其布爾值表示標註是否可以在單個目標位置中應用多次（默認為false）。
以下是一個示例，其中包含額外的屬性和屬性的標註類型:
annotationTypes:
complexValueType:
allowMultiple: true
properties:
prop1: integer
prop2: string
prop3: boolean標註可以應用於（在）多個根級別目標位置，包括API的根級別、資源類型、特性、數據類型、文檔項、安全方案、庫、覆蓋層、擴展和其他標註類型。
標註也可以應用於安全方案設置、資源、方法、響應聲明、請求主體、響應主體和命名示例。
要將標註類型限制為一種或多種特定目標位置類型，您需要定義其allowedTargets屬性。
為了將標註類型限制為單個目標位置類型，您需要將allowedTargets屬性分配一個字符串值，表示該目標位置類型:
annotationTypes:
supportsOnlyOneTargetLocationType:
allowedTargets: TypeDeclaration要為標註類型允許多種目標位置類型，您需要將allowedTargets屬性分配一個字符串數組，表示這些目標位置類型:
annotationTypes:
supportsMultipleTargetLocationTypes:
allowedTargets: [ Library, Overlay, Extension ]如果allowedTargets屬性未定義於標註類型中，則默認情況下，該標註類型可以應用於任何支持的目標位置類型。
一旦您在 RAML API 規範的根級別定義了 標註類型，您就需要將其應用到其預期的目標位置，並在每個實例中提供其屬性值。 在目標位置應用一個 標註類型，簡單地稱為該目標位置上的 標註。
要應用一個 標註類型，請將 標註類型名稱，用括號 () 括起來，作為目標位置的屬性，並提供 標註類型值，該值將由 標註類型用於特定目標。 如果 標註類型位於 RAML 庫中，則需要將 庫引用與一個點 (.) 組合，然後是 標註類型名稱。
以下示例展示瞭如何將上述代碼片段中列出的 標註類型應用到 API 的各種 資源和 方法:
/foos:
type: myResourceTypes.collection
(simpleImplicitStringValueType): alpha
...
get:
(simpleExplicitStringValueType): beta
...
/{fooId}:
type: myResourceTypes.item
(complexValueType):
prop1: 4
prop2: testing
prop3: true一個潛在的 標註 的使用場景是為 API 定義和配置測試用例。
假設我們想要開發一個能夠根據 標註 生成一系列測試用例的 RAML 處理工具。我們可以定義以下 標註類型:
annotationTypes:
testCase:
allowedTargets: [ Method ]
allowMultiple: true
usage: |
使用此標註來聲明一個測試用例。
可以在每個位置多次應用此標註。
properties:
scenario: string
setupScript?: string[]
testScript: string[]
expectedOutput?: string
cleanupScript?: string[]然後我們可以為我們的 /foos 資源配置一系列測試用例，通過應用 標註 如下所示：
/foos:
type: myResourceTypes.collection
get:
(testCase):
scenario: 無 Foos
setupScript: deleteAllFoosIfAny
testScript: getAllFoos
expectedOutput: ""
(testCase):
scenario: 一個 Foos
setupScript: [ deleteAllFoosIfAny, addInputFoos ]
testScript: getAllFoos
expectedOutput: '[ { "id": 999, "name": Joe } ]'
cleanupScript: deleteInputFoos
(testCase):
scenario: 多個 Foos
setupScript: [ deleteAllFoosIfAny, addInputFoos ]
testScript: getAllFoos
expectedOutput: '[ { "id": 998, "name": "Bob" }, { "id": 999, "name": "Joe" } ]'
cleanupScript: deleteInputFoos
首先，我們演示瞭如何使用頂級 annotationTypes 屬性聲明 註解類型，並列舉了允許應用於的目標位置的類型。
接下來，我們演示瞭如何在我們的 API 中應用 註解，並説明如何限制給定 註解 可以應用的類型。
最後，我們通過定義可能由測試生成工具支持的 註解類型，並展示如何將這些 註解 應用到 API。
有關在 RAML 中使用 註解 的更多信息，請訪問 RAML 1.0 規範。
