1. Введение
В этой четвертой статье из нашей серии о RAML — языке моделирования RESTful API — мы демонстрируем , как использовать аннотации для определения пользовательских свойств для спецификации RAML API. Этот процесс также называется расширением метаданных спецификации.
Аннотации могут использоваться для предоставления крючков для инструментов обработки RAML, требующих дополнительных спецификаций, которые выходят за рамки официального языка.
2. Объявление типов аннотаций
Один или несколько типов аннотаций могут быть объявлены с использованием свойства annotationTypes верхнего уровня .
В самых простых случаях имя типа аннотации — это все, что необходимо для его указания, и в этом случае значение типа аннотации неявно определяется как строка:
annotationTypes:
simpleImplicitStringValueType:
Это эквивалентно более явному определению типа аннотации, показанному здесь:
annotationTypes:
simpleExplicitStringValueType:
type: string
В других случаях спецификация типа аннотации будет содержать объект значения, который считается объявлением типа аннотации .
В этих случаях тип аннотации определяется с использованием того же синтаксиса, что и тип данных, с добавлением двух необязательных атрибутов: allowTargets , значением которого является либо строка, либо массив строк, ограничивающий типы целевых местоположений, к которым может быть привязана аннотация . apply и 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 , применив аннотации следующим образом:
/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 с помощью пользовательских свойств, называемых аннотациями .
Во- первых, мы показали, как объявлять типы аннотаций, используя свойство annotationTypes верхнего уровня, и перечислили типы целевых местоположений, к которым их можно применять.
Далее мы продемонстрировали, как применять аннотации в нашем API, и отметили, как ограничить типы целевых местоположений, к которым может применяться данная аннотация .
Наконец, мы представили потенциальный вариант использования, определив типы аннотаций , которые потенциально могут поддерживаться инструментом генерации тестов, и показав, как можно применить эти аннотации к API.
Дополнительные сведения об использовании аннотаций в RAML см . в спецификации RAML 1.0 .
Вы можете просмотреть полную реализацию определения API, используемого для этого руководства, в проекте github .