Рубрики
Без рубрики

Модульный RAML Использование включает в себя, библиотеки, накладки и расширения

Научитесь модульизировать определение RAML с помощью включений, библиотек, накладок и расширений.

Автор оригинала: baeldung.

1. Введение

В нашем первый два статьи на RAML – RESTful API Моделирование Язык – мы ввели некоторые основные синтаксис, в том числе использование типов данных и схемы JSON, и мы показали, как упростить определение RAML путем извлечения общих шаблонов в типы ресурсов и черты .

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

2. Наш API

Для целей этой статьи мы сосредоточимся на части нашего API, включающей тип сущности, называемый Фу .

Вот ресурсы, составить наш API:

  • ПОЛУЧИТЬ /api/v1/foos
  • POST /api/v1/foos
  • ПОЛУЧИТЬ /api/v1/foos/«fooId»
  • PUT /api/v1/foos/«fooId»
  • УДАЛИТЬ /api/v1/foos/«fooId»

3. Включает в себя

Цель включают заключается в модульизации сложного значения свойства в определении RAML путем размещения стоимости свойства во внешнем файле.

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

3.1. Общее использование и синтаксис

!включить тег принимает один аргумент: расположение внешнего файла, содержащего значение свойства. Это местоположение может быть абсолютным URL, путь по отношению к корневому файлу RAML, или путь по отношению к включая файл.

Местоположение, начинаюееся с форвардного слэш (/), указывает путь относительно расположения корневого файла RAML, а местоположение, начинаюееся без слэш, интерпретируется как относительно местоположения включая файл.

Логическим следствием последнего является то, что включенный файл сам по себе может содержать другие !включить Директивы.

Вот пример, показывающий все три использования !включить ярлык:

#%RAML 1.0
title: Baeldung Foo REST Services API
...
types: !include /types/allDataTypes.raml
resourceTypes: !include allResourceTypes.raml
traits: !include http://foo.com/docs/allTraits.raml

3.2. Типиные фрагменты

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

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

Хотя это и не требуется, первая строка включают файл, который является типированный фрагмент может быть идентификатор фрагмента RAML следующего формата:

#%RAML 1.0

Например, первая строка типированный фрагмент файл для черта Было бы:

#%RAML 1.0 Trait

Если используется идентификатор фрагмента, то содержимое файла должно содержать только действительный RAML для указанного типа фрагмента.

Давайте сначала рассмотрим часть черты раздел нашего API:

traits:
  - hasRequestItem:
      body:
        application/json:
          type: <>
  - hasResponseItem:
      responses:
          200:
            body:
              application/json:
                type: <>
                example: !include examples/<>.json

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

traits:
  - hasRequestItem: !include traits/hasRequestItem.raml
  - hasResponseItem: !include traits/hasResponseItem.raml

Затем мы писали типированный фрагмент файл имеетRequestItem.raml :

#%RAML 1.0 Trait
body:
  application/json:
    type: <>

типированный фрагмент файл имеетResponseItem.raml будет выглядеть так:

#%RAML 1.0 Trait
responses:
    200:
      body:
        application/json:
          type: <>
          example: !include /examples/<>.json

4. Библиотеки

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

4.1. Определение библиотеки

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

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

Давайте перепишем наши черты раздел в качестве библиотечный файл:

#%RAML 1.0 Library
# This is the file /libraries/traits.raml
usage: This library defines some basic traits
traits:
  hasRequestItem:
    usage: Use this trait for resources whose request body is a single item
    body:
      application/json:
        type: <>
  hasResponseItem:
    usage: Use this trait for resources whose response body is a single item
    responses:
        200:
          body:
            application/json:
              type: <>
              example: !include /examples/<>.json

4.2. Применение библиотеки

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

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

#%RAML 1.0
title: Baeldung Foo REST Services API
uses:
  mySecuritySchemes: !include libraries/security.raml
  myDataTypes: !include libraries/dataTypes.raml
  myResourceTypes: !include libraries/resourceTypes.raml
  myTraits: !include libraries/traits.raml

4.3. Ссылки на библиотеку

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

Вы можете вспомнить из наша предыдущая статья как мы рефакторинг наших типы ресурсов с помощью черты что мы определили. Следующий пример показывает, как переписать наш “пункт” тип ресурса в качестве библиотека, как включить черты библиотечный файл (см. выше) в новом библиотечный , и как ссылаться на черты путем приставки черта имена с их библиотечный квалификатор имени (” myTraits “):

#%RAML 1.0 Library
# This is the file /libraries/resourceTypes.raml
usage: This library defines the resource types for the API
uses:
  myTraits: !include traits.raml
resourceTypes:
  item:
    usage: Use this resourceType to represent any single item
    description: A single <>
    get:
      description: Get a <> by <>
      is: [ myTraits.hasResponseItem, myTraits.hasNotFound ]
    put:
      description: Update a <> by <>
      is: [ myTraits.hasRequestItem, myTraits.hasResponseItem, myTraits.hasNotFound ]
    delete:
      description: Delete a <> by <>
      is: [ myTraits.hasNotFound ]
      responses:
        204:

5. Накладки и расширения

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

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

5.1. Определение

Первая строка файла наложения или расширения должна быть отформатирована следующим образом:

RAML 1.0 Overlay

И первая строка файла наложения должна быть отформатирована аналогичным образом:

RAML 1.0 Extension

5.2. Ограничения использования

При использовании набора накладывает и/или расширения , все они должны относиться к одному и тому же мастеру файла RAML. Кроме того, инструменты обработки RAML обычно ожидают корневой файл RAML и все наложение и расширение файлы, чтобы иметь общее расширение файла (например, “.raml”).

5.3. Использование случаев для накладок

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

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

#%RAML 1.0
title: API for REST Services used in the RAML tutorials on Baeldung.com
documentation:
  - title: Overview
  - content: |
      This document defines the interface for the REST services
      used in the popular RAML Tutorial series at Baeldung.com.
  - title: Copyright
  - content: Copyright 2016 by Baeldung.com. All rights reserved.

Вот как мы определим наложения испанского языка для этого раздела:

#%RAML 1.0 Overlay
# File located at (archivo situado en):
# /overlays/es_ES/documentationItems.raml
masterRef: /api.raml
usage: |
  To provide user documentation and other descriptive text in Spanish
  (Para proporcionar la documentación del usuario y otro texto descriptivo
  en español)
title: |
  API para servicios REST utilizados en los tutoriales RAML
  en Baeldung.com
documentation:
  - title: Descripción general
  - content: |
      Este documento define la interfaz para los servicios REST
      utilizados en la popular serie de RAML Tutorial en Baeldung.com.
  - title: Derechos de autor
  - content: |
      Derechos de autor 2016 por Baeldung.com.
      Todos los derechos reservados.

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

5.4. Использование случаев для расширения

Как вы можете сделать вывод из названия, расширения используются для расширения API путем добавления новых поведений и/или изменения существующего поведения API. Аналогией из мира объектно-ориентированного программирования будет подкласс, расширяющий суперкласс, где подкласс может добавлять новые методы и/или переопределять существующие методы. Расширение может также расширить нефункциональные аспекты API.

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

Ниже приведена расширение который переопределяет версию нашего API и добавляет ресурсы, недоступные в предыдущей версии:

#%RAML 1.0 Extension
# File located at:
# /extensions/en_US/additionalResources.raml
masterRef: /api.raml
usage: This extension defines additional resources for version 2 of the API.
version: v2
/foos:
  /bar/{barId}:
    get:
      description: |
        Get the foo that is related to the bar having barId = {barId}
      typeName: Foo
      queryParameters:
        barId?: integer
        typeName: Foo
        is: [ hasResponseItem ]

А вот и испаноязычная наложение для этого расширение :

#%RAML 1.0 Overlay
# Archivo situado en:
# /overlays/es_ES/additionalResources.raml
masterRef: /api.raml
usage: |
  Se trata de un español demasiado que describe los recursos adicionales
  para la versión 2 del API.
version: v2
/foos:
  /bar/{barId}:
    get:
      description: |
        Obtener el foo que se relaciona con el bar tomando barId = {barId}

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

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

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

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

Чтобы узнать еще больше о методах модульизации RAML, пожалуйста, посетите RAML 1.0 спецификации .

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

Читайте ещё по теме: