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

1. Вступление

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

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

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

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

В простейшем случае тип annotation name - это все, что нужно для его указания, и в этом случае тип annotation value неявно определяется как строка:

annotationTypes:
  simpleImplicitStringValueType:

Это эквивалентно более явному определению annotation type , показанному здесь:

annotationTypes:
  simpleExplicitStringValueType:
    type: string

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

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

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

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

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

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

Annotations могут применяться (использоваться в) к нескольким целевым местоположениям корневого уровня, включая корневой уровень самого API, resource types , traits , data types , documentation items , security circuit , libraries , overlays , extensions и другие annotation types .

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

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

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

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

annotationTypes:
  supportsOnlyOneTargetLocationType:
    allowedTargets: TypeDeclaration

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

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

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

[[applying]]

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

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

====  **  3.1. Синтаксис**

Чтобы применить __annotation type__, добавьте __annotation type name__, заключенный в круглые скобки (), в качестве атрибута целевого местоположения и предоставьте __annotation type value__ свойства, которые __annotation type__ будет использовать для этой конкретной цели. Если __annotation type__ находится в RAML __library__, то вы должны объединить __library__ ссылку, за которой следует точка (.), За которой следует __annotation type name.__

====  **  3.2. Пример**

Вот пример, показывающий, как мы могли бы применить некоторые из __annotation types__, перечисленных в приведенных выше фрагментах кода, к различным __resources__ и __methods__ нашего API:

[source,javascript,gutter:,true]

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

4. Вариант использования

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

Предположим, что мы хотели разработать инструмент обработки RAML, который может генерировать серию тестов для нашего API на основе annotations Мы могли бы определить следующее 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[]----

Затем мы можем настроить серию тестов для нашего ресурса __/foos__, применив __annotations__ следующим образом:

[source,javascript,gutter:,true]

----/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 с помощью пользовательских свойств, называемых annotations .

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

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

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

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

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

«** Предыдущая

Modular Использование RAML включает в себя, библиотеки, оверлеи и расширения

TOC