«1. Введение

В этой четвертой статье из нашей серии о RAML — языке моделирования RESTful API — мы демонстрируем, как использовать аннотации для определения пользовательских свойств для спецификации RAML API. Этот процесс также называется расширением метаданных спецификации.

Аннотации могут использоваться для предоставления хуков для инструментов обработки RAML, требующих дополнительных спецификаций, выходящих за рамки официального языка.

2. Объявление типов аннотаций

Один или несколько типов аннотаций могут быть объявлены с использованием свойства annotationTypes верхнего уровня.

В простейших случаях имя типа аннотации — это все, что необходимо для его указания, и в этом случае значение типа аннотации неявно определяется как строка: 

annotationTypes:
  simpleImplicitStringValueType:

Это эквивалентно более здесь показано явное определение типа аннотации: 

annotationTypes:
  simpleExplicitStringValueType:
    type: string

В других случаях спецификация типа аннотации будет содержать объект значения, который считается объявлением типа аннотации.

В этих случаях тип аннотации определяется с использованием того же синтаксиса, что и тип данных, с добавлением двух необязательных атрибутов: allowTargets, значением которого является либо строка, либо массив строк, ограничивающих типы целевых местоположений, к которым аннотация может быть применена, и allowMultiple, логическое значение которого указывает, может ли аннотация применяться более одного раза в пределах одной цели (по умолчанию — false).

Вот краткий пример объявления типа аннотации, содержащего дополнительные свойства и атрибуты: 

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

2.1. Целевые расположения, поддерживающие использование аннотаций

Аннотации могут применяться (использоваться) к нескольким целевым расположениям корневого уровня, включая корневой уровень самого API, типы ресурсов, признаки, типы данных, элементы документации, схемы безопасности, библиотеки , наложения, расширения и другие типы аннотаций.

Аннотации также можно применять к параметрам схемы безопасности, ресурсам, методам, объявлениям ответов, телам запросов, телам ответов и именованным примерам.

2.2. Ограничение целей типа аннотации

Чтобы ограничить тип аннотации одним или несколькими конкретными типами целевого местоположения, вы должны определить его атрибут allowTargets.

При ограничении типа аннотации одним типом целевого местоположения вы должны присвоить атрибуту allowTargets строковое значение, представляющее этот тип целевого местоположения: 

annotationTypes:
  supportsOnlyOneTargetLocationType:
    allowedTargets: TypeDeclaration

Чтобы разрешить несколько типов целевого местоположения для типа аннотации, вы должны назначить атрибут allowTargets представляет собой массив строковых значений, представляющих эти типы целевых местоположений: 

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

Если атрибут allowTargets не определен для типа аннотации, то по умолчанию этот тип аннотации может применяться к любому из поддерживаемых типов целевых местоположений. .

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, который может генерировать серию тестов для нашего 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[]

«

/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

«Затем мы могли бы настроить серию тестов для нашего ресурса /foos, применяя аннотации следующим образом:

5. Заключение

В этом руководстве мы показали, как расширить метаданные для спецификации RAML API с помощью использование пользовательских свойств, называемых аннотациями.

Сначала мы показали, как объявлять типы аннотаций с помощью свойства annotationTypes верхнего уровня, и перечислили типы целевых местоположений, к которым их можно применять.

Далее мы продемонстрировали, как применять аннотации в нашем API, и отметили, как ограничить типы целевых местоположений, к которым может применяться данная аннотация.

Наконец, мы представили потенциальный вариант использования, определив типы аннотаций, которые потенциально могут поддерживаться инструментом генерации тестов, и показав, как можно применить эти аннотации к API.

Дополнительные сведения об использовании аннотаций в RAML см. в спецификации RAML 1.0.

« Previous

Modular RAML Using Includes, Libraries, Overlays and Extensions