Определить пользовательские свойства RAML с помощью аннотации

1. Введение

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

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

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

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

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

annotationTypes:
  simpleImplicitStringValueType:

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

annotationTypes:
  simpleExplicitStringValueType:
    type: string

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

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

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

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

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

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

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

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

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

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

annotationTypes:
  supportsOnlyOneTargetLocationType:
    allowedTargets: TypeDeclaration

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

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

Если разрешеноTargets атрибут не определяется на аннотация типа , то по умолчанию, что аннотация типа могут быть применены к любому из типов вспомогательного целевого местоположения.

3. Применение типов аннотации

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

3.1. Синтаксис

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

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 ресурс, применяя аннотации следующим образом:

/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. Заключение

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

Во-первых, мы показали, как типы аннотации с помощью системы верхнего аннотацияТипы собственности и перечислил типы целевых мест, к которым они могут быть применены.

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

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

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

Вы можете просмотреть полную реализацию определения API, используемого для этого учебника в проект github .