Define Custom RAML Properties Using Annotations – 使用注解定义自定义RAML属性

1. Introduction

1.介绍

In this, the fourth article in our series on RAML – the RESTful API Modeling Language – we demonstrate how to use annotations to define custom properties for a RAML API specification. This process is also referred to as extending the metadata of the specification.

在这篇关于RAML（RESTful API建模语言）系列的第四篇文章中，我们展示了如何使用注释来为RAML API规范定义自定义属性。这个过程也被称为扩展规范的元数据。

Annotations may be used to provide hooks for RAML processing tools requiring additional specifications that lie outside the scope of the official language.

注释可以用来为RAML处理工具提供钩子，这些工具需要超出官方语言范围的额外规范。

2. Declaring Annotation Types

2.声明注解类型

One or more annotation types may be declared using the top-level annotationTypes property.

可以使用顶层的annotationTypes属性来声明一个或多个注释类型。

In the simplest of cases, the annotation type name is all that is needed to specify it, in which case the annotation type value is implicitly defined to be a string:

在最简单的情况下，注解类型名是指定它所需要的全部内容，在这种情况下，注解类型值被隐式地定义为一个字符串。

annotationTypes:
  simpleImplicitStringValueType:

This is the equivalent to the more explicit annotation type definition shown here:

这相当于这里显示的更明确的注释类型定义。

annotationTypes:
  simpleExplicitStringValueType:
    type: string

In other cases, an annotation type specification will contain a value object that is considered to be the annotation type declaration.

在其他情况下，注解类型规范将包含一个被认为是注解类型声明的值对象。

In these cases, the annotation type is defined using the same syntax as a data type with the addition of two optional attributes: allowedTargets, whose value is either a string or an array of strings limiting the types of target locations to which an annotation may be applied, and allowMultiple, whose boolean value states whether or not the annotation may be applied more than once within a single target (default is false).

在这些情况下，标注类型使用与数据类型相同的语法进行定义，并增加了两个可选的属性。allowedTargets，其值是一个字符串或一个字符串数组，限制了可应用annotation的目标位置的类型，以及allowMultiple，其布尔值说明annotation是否可在单个目标中应用一次以上（默认是false）。

Here is a brief example declaring an annotation type containing additional properties and attributes:

下面是一个简单的例子，声明了一个包含额外属性的注解类型。

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

2.1. Target Locations Supporting the Use of Annotations

2.1.支持使用注释的目标地点

Annotations may be applied to (used in) several root-level target locations, including the root level of the API itself, resource types, traits, data types, documentation items, security schemes, libraries, overlays, extensions, and other annotation types.

注释可应用于（用于）几个根级别的目标位置，包括API本身的根级别、资源类型、traits。数据类型、文档项目、安全方案、库、覆盖、扩展和其它注解类型。

Annotations may also be applied to security scheme settings, resources, methods, response declarations, request bodies, response bodies, and named examples.

注释也可应用于安全方案设置、资源、方法、响应声明、请求体、响应体和命名的示例。

2.2. Restricting an Annotation Type’s Targets

2.2.限制注解类型的目标

To restrict an annotation type to one or more specific target location types, you would define its allowedTargets attribute.

要将一个注释类型限制为一个或多个特定的目标位置类型，您需要定义其allowedTargets属性。

When restricting an annotation type to a single target location type, you would assign the allowedTargets attribute a string value representing that target location type:

当把一个注释类型限制为单一的目标位置类型时，您将为allowedTargets属性分配一个代表该目标位置类型的字符串值。

annotationTypes:
  supportsOnlyOneTargetLocationType:
    allowedTargets: TypeDeclaration

To allow multiple target location types for an annotation type, you would assign the allowedTargets attribute an array of string values representing those target location types:

要为一个注解类型允许多个目标位置类型，您将为allowedTargets属性分配一个代表这些目标位置类型的字符串值数组。

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

If the allowedTargets attribute is not defined on an annotation type, then by default, that annotation type may be applied to any of the supporting target location types.

如果allowedTargets属性没有在annotation type上定义，那么默认情况下，该annotation type可以应用于任何支持的目标位置类型。

3. Applying Annotation Types

3.应用注释类型

Once you have defined the annotation types at the root level of your RAML API spec, you would apply them to their intended target locations, providing their property values at each instance. The application of an annotation type within a target location is referred to simply as an annotation on that target location.

一旦你在RAML API规范的根层定义了注释类型，你将把它们应用到它们的目标位置，在每个实例中提供它们的属性值。在目标位置中应用注解类型被简单地称为对该目标位置的注解。

3.1. Syntax

3.1.语法

In order to apply an annotation type, add the annotation type name enclosed in parentheses () as an attribute of the target location and provide the annotation type value properties that the annotation type is to use for that specific target. If the annotation type is in a RAML library, then you would concatenate the library reference followed by a dot (.) followed by the annotation type name.

为了应用一个注解类型，添加括号（）内的注解类型名称作为目标位置的一个属性，并提供注解类型值属性，该注解类型将用于该特定目标。如果注解类型在RAML的库中，那么你将连接库的引用，后面是点（.）和注解类型名称。

3.2. Example

3.2.例子

Here is an example showing how we might apply some of the annotation types listed in the above code snippets to various resources and methods of our API:

下面是一个例子，展示了我们如何将上述代码片段中列出的一些注释类型应用于我们API的各种资源和方法。

/foos:
  type: myResourceTypes.collection
  (simpleImplicitStringValueType): alpha
  ...
  get:
    (simpleExplicitStringValueType): beta
  ...
  /{fooId}:
    type: myResourceTypes.item
    (complexValueType):
      prop1: 4
      prop2: testing
      prop3: true

4. Use Case

4.使用案例

One potential use case for annotations would be defining and configuring test cases for an API.

注释的一个潜在用例是为API定义和配置测试案例。

Suppose we wanted to develop a RAML processing tool that can generate a series of tests against our API based on annotations. We could define the following annotation type:

假设我们想开发一个RAML处理工具，它可以根据注释针对我们的API生成一系列的测试。我们可以定义以下注释类型。

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[]

We could then configure a series of tests cases for our /foos resource by applying annotations as follows:

然后，我们可以通过应用注释，为我们的/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. Conclusion

5.结论

In this tutorial, we have shown how to extend the metadata for a RAML API specification through the use of custom properties called annotations.

在本教程中，我们展示了如何通过使用名为annotations的自定义属性来扩展RAML API规范的元数据。

First, we showed how to declare annotation types using the top-level annotationTypes property and enumerated the types of target locations to which they are allowed to be applied.

首先，我们展示了如何使用顶层的annotationTypes属性来声明annotation类型，并枚举了允许应用这些类型的目标位置。

Next, we demonstrated how to apply annotations in our API and noted how to restrict the types of target locations to which a given annotation can be applied.

接下来，我们演示了如何在我们的API中应用注释，并指出如何限制特定注释可以应用的目标位置的类型。

Finally, we introduced a potential use case by defining annotation types that could potentially be supported by a test generation tool and showing how one might apply those annotations to an API.

最后，我们通过定义测试生成工具可能支持的注释类型，并展示如何将这些注释应用于API，从而介绍了一个潜在的使用案例。

For more information about the use of annotations in RAML, please visit the RAML 1.0 spec.

关于RAML中使用注释的更多信息，请访问RAML 1.0规范。

You can view the full implementation of the API definition used for this tutorial in the github project.

您可以在github项目中查看本教程中使用的API定义的完整实现。