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

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

В нашей ссылке:/raml-restful-api-моделирование-language-tutorial[первая]ссылка:/simple-raml-with-resource-types-types-traits[две]статьи о RAML - языке моделирования RESTful API - мы представили некоторый базовый синтаксис, включая использование типов данных и схемы JSON, и мы показали, как упростить определение RAML путем извлечения общих шаблонов в resource types и traits .

В этой статье мы покажем, как вы можете разбить определение RAML API на модули , используя include , libraries , overlays и extensions

2. Наш API

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

Вот ресурсы, из которых состоит наш API:

GET /api/v1/foos
POST /api/v1/foos
GET /api/v1/foos/\ {fooId}
PUT /api/v1/foos/\ {fooId}
DELETE /api/v1/foos/\ {fooId}

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

Цель include состоит в том, чтобы модулировать значение комплексного свойства в определении RAML, поместив значение свойства во внешний файл.

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

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

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

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

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

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

#%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. Типизированные фрагменты

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

Вы также можете использовать типированные фрагменты для определения документации пользователя , name examples , annotations , libraries , overlays и extensions Мы расскажем об использовании overlays и extensions позже в этой статье.

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

#%RAML 1.0 <fragment-type>

Например, первая строка typed фрагмента файла для trait будет:

#%RAML 1.0 Trait

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

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

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

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

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

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

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

Typed фрагмент файл hasResponseItem.raml будет выглядеть следующим образом:

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

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

RAML libraries может использоваться для модуляции любого числа и комбинации data types , security Programs , resource types , traits и annotations .

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

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

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

Давайте перепишем наш traits раздел как library файл:

#%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: <<typeName>>
  hasResponseItem:
    usage: Use this trait for resources whose response body is a single item
    responses:
        200:
          body:
            application/json:
              type: <<typeName>>
              example: !include/examples/<<typeName>>.json

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

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

После того как мы создали libraries для наших схем security , data types , resource types и traits , мы можем применить libraries к корневому файлу 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. Ссылка на библиотеку

На library ссылаются путем объединения имени library , точки (.) И имени элемента (например, типа данных, типа ресурса, признака и т. Д.), На который ссылаются.

Вы можете вспомнить по ссылке:/simple-raml-with-resource-types-and-traits[наша предыдущая статья], как мы реорганизовали наши resource types , используя traits , которые мы определили. В следующем примере показано, как переписать наш «элемент» resource type в виде library, как включить файл traits library (показанный выше) в новый library и как ссылаться на traits , добавив префикс trait к именам их квалификаторам library name ( « 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 <<typeName>>
    get:
      description: Get a <<typeName>> by <<resourcePathName>>
      is:[myTraits.hasResponseItem, myTraits.hasNotFound]    put:
      description: Update a <<typeName>> by <<resourcePathName>>
      is:[myTraits.hasRequestItem, myTraits.hasResponseItem, myTraits.hasNotFound]    delete:
      description: Delete a <<typeName>> by <<resourcePathName>>
      is:[myTraits.hasNotFound]      responses:
        204:

5. Наложения и расширения

Overlays и extensions - это модули, определенные во внешних файлах, которые используются для расширения API. An overlay используется для расширения не связанных с поведением аспектов API, таких как описания, инструкции по использованию и элементы пользовательской документации, тогда как extension используется для расширения или переопределения поведенческих аспектов API.

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

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

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

RAML 1.0 Overlay

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

RAML 1.0 Extension

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

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

5.3. Варианты использования для наложений

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

Обычный вариант использования overlays - предоставление пользовательской документации и других описательных элементов на нескольких языках. Давайте перепишем название нашего 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 documentación del usuario y otro texto descriptivo
  en español)
title: |
  API para servicios REST utilizados en los tutoriales RAML
  en Baeldung.com
documentation:
  - title: Descripció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.

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

5.4. Используйте Случаи для Расширений

Как следует из названия, extensions используются для расширения API путем добавления новых поведений и/или изменения существующих поведений API.

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

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

Ниже приведено extension , которое переопределяет версию нашего 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]----

А вот __overlay__ на испанском языке для этого __extension__:

[source,javascript,gutter:,true]

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

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

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

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

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

Чтобы узнать больше о методах модуляции RAML, посетите страницу https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#modularization[RAML 1.0 spec],

Вы можете просмотреть **  полную реализацию **  определения API, используемого для этого руководства, по адресу https://github.com/eugenp/tutorials/tree/master/raml/modularization[the проект github].

Следующий ** "**

https://www.baeldung.com/raml-custom-properties-with-annotations[Define пользовательские свойства RAML с использованием аннотаций]

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

https://www.baeldung.com/simple-raml-with-resource-types-and-traits[Eliminate
Избыточности в RAML с типами и характеристиками ресурсов]

TOC