raml-custom-properties-with-annotations

Posted on: 2019-10-08 2019-10-08
Tags: RAML, REST

Define Custom RAML Properties Using Annotations

REST
RAML

1. Introduction

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.

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

2. Declaring Annotation Types

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

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).

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

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.

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

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

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:

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:

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.

3. Applying Annotation Types

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.

3.1. Syntax

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.

3.2. Example

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:

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

4. Use Case

One potential use case for annotations would be defining and
configuring test cases for an 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:

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

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

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.

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.

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.

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

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

« Previous

Modular
RAML Using Includes, Libraries, Overlays and Extensions

getdocs

3043