使用註解定義自定義RAML屬性

<div>
 <a class="article-series-header" href="javascript:void(0);">該文章是系列的一部分</a>
 <div>
  <div>
   • 介紹 RAML – RESTful API 建模語言
   <br>
   • 使用資源類型和特性消除 RAML 中的冗餘
   <br>
   • 使用包含、庫、覆蓋和擴展進行模塊化 RAML
   <br>
   <div>
    • 使用註釋定義自定義 RAML 屬性（當前文章）
   </div>
  </div>
  </div>
  <!-- end of article series inner -->
 </div>
 <!-- .article-series-links -->
</div>

1. 引言

在本文檔中，這是我們關於 RAML – RESTful API 建模語言系列文章的第四篇，我們將演示如何使用註釋定義自定義屬性，用於 RAML API 規範。這種過程也被稱為擴展規範的元數據。

註釋可用於為 RAML 處理工具提供鈎子，這些工具需要超出官方語言範圍的其他規範。

2. 聲明標註類型可以使用頂層屬性 annotationTypes 聲明一個或多個 annotation types。

在最簡單的案例中，annotation type name 即可指定它，此時 annotation type value 默認為字符串:

annotationTypes:
  simpleImplicitStringValueType:

這與更明確的標註類型定義相同，如下所示：

annotationTypes:
  simpleExplicitStringValueType:
    type: string

在其他情況下，一個標註類型規範會包含一個值對象，該對象被認為是標註類型聲明。

在這些情況下，標註類型使用與數據類型相同的語法定義，並添加了兩個可選屬性：allowedTargets，其值可以是字符串或字符串數組，限制了標註可以應用於的目標位置類型，以及allowMultiple，其布爾值表示標註是否可以在單個目標中多次應用（默認值為false）。

下面是一個簡短的示例，聲明瞭一個包含附加屬性和屬性的標註類型：

annotationTypes:
  complexValueType:
    allowMultiple: true
    properties:
      prop1: integer
      prop2: string
      prop3: boolean

2.1. 支持使用註釋的目標位置

註釋可應用於多個根級別目標位置，包括 API 本身根級別、資源類型、特性、數據類型、文檔項、安全方案、庫、覆蓋層、擴展以及其他註釋類型。

註釋也可應用於安全方案設置、資源、方法、響應聲明、請求主體、響應主體以及命名示例。

2.2. 限制標註類型的目標

為了將 標註類型限制為一種或多種特定的目標位置類型，您需要定義其 allowedTargets 屬性。

當將 標註類型限制為單個目標位置類型時，您需要將 allowedTargets 屬性分配一個字符串值，該字符串值表示該目標位置類型。

annotationTypes:
  supportsOnlyOneTargetLocationType:
    allowedTargets: TypeDeclaration

為了允許一個 標註類型 具有多個目標位置類型，您應該將 allowedTargets 屬性賦值為一個字符串數組，其中包含這些目標位置類型：

annotationTypes:
  supportsMultipleTargetLocationTypes:
    allowedTargets: [ Library, Overlay, Extension ]

如果 allowedTargets 屬性未在 annotation type 中定義，則該 annotation type 默認情況下可以應用於任何支持的目標位置類型。

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: true

4. 使用場景

標註的一個潛在用途是為 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 規範的元數據。

首先，我們展示瞭如何使用頂層屬性  聲明 ，並列舉了允許應用的目標位置的類型。

接下來，我們演示瞭如何在我們的 API 中應用 ，並説明了如何限制給定  可以應用的類型。

最後，我們通過定義可能由測試生成工具支持的 ，並展示如何將這些  應用到 API 中，引入了一個潛在的使用案例。

有關在 RAML 中使用  的更多信息，請訪問 RAML 1.0 規範。

知識庫 / REST RSS 訂閱