О RAML — языке разметки, используемом для описания RESTful API, мы уже писали. В обсуждении статьи на Хабрахабре один из читателей заметил, что RAML уже давно не обновляется, чуть ли не с лета 2014 года.
Несколько месяцев формат RAML был существенно усовершенствован. Новая спецификация версии 1.0 была опубликована на официальном сайте относительно недавно, в начале октября 2015 года. По сравнению с предыдущей версией (0.8) в неё было внесено много изменений и дополнений. О наиболее значительных нововведениях мы подробно расскажем в этой статье.
Типы данных
Самая важная новация в RAML 1.0 — это поддержка типов данных. Теперь во вводной части документа можно очень подробно описывать все типы данных, с которыми работает API:
#%RAML 1.0 title: New API mediaType: application/json types: Person: type: object # properties: firstname: string lastname: string is_our_employee: boolean Document: type: object properties: Author title: string signing_date: date Типы данных, определённые в спецификации, можно использовать в дальнейшем при описании тел ответов, параметров URI, заголовков и query-парамертров, например:
/documents/{documentId}: get: responses: 200: body: application/json: type: Document Примеры: расширенные возможности
В документации к любому API желательно приводить как можно больше примеров.
В RAML 1.0 примеры можно добавлять в любую часть документа. Примеры могут представлены как в формате JSON, так и YAML:
#%RAML 1.0 title: New API mediaType: application/json types: Person: type: object # properties: firstname: string lastname: string is_our_employee: boolean examples: { firstname: Alexander lastname: Ivanov is_our_employee: true } Благодаря примерам описание API становится более понятным и наглядным.
Аннотации
С помощью аннотаций в спецификации RAML можно вставлять дополнительные метаданные. Эта возможность полезна при проектировании API: в аннотации можно добавить информацию, которая окажется полезной в дальнейшем (для тестирования, дополнения документации и т.п.).
Рассмотрим простой пример (взят из официальной документации):
#%RAML 1.0 title: Illustrating annotations mediaType: application/json annotationTypes: experimental: /groups: (experimental): Во вводной части документа (атрибут annotationTypes) описывается общий формат аннотаций. Далее один из эндпоинтов API помечен как экспериментальный.
Аннотации можно использовать и в более сложных ситуациях — например, для описания тест-кейсов:
#%RAML 1.0 title: Testing annotations mediaType: application/json 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 /documents: type: myResourceTypes.collection get: (testCase): scenario: No Documents setupScript: deleteAllDocuments testScript: getAllDocuments expectedOutput: [ ] (testCase): scenario: One Document setupScript: [ deleteAllDocuments, addDocs ] testScript: getAllDocuments expectedOutput: '[ { "id": 999, "author": "John Smith" } ]' (testCase): scenario: Multiple Documents setupScript: [ deleteAllDocuments, addDocs ] testScript: getAllDocuments expectedOutput: '[ { "id": 998, "author": "Bob Brown" }, { "id": 999, "name": "John Smith" } ]' Библиотеки
Ещё одно нововведение RAML 1.0 — библиотеки. Библиотекой называется файл, в который вынесены профили, типы данных и другая информация, помещаемая во вводную часть документа. Теперь в новом документе можно не расписывать подробно вводную часть, а сослаться на уже имеющиеся библиотеки. Такая практика напоминает подключение внешних библиотек и модулей в программном коде.
Приведём пример библиотеки:
#%RAML 1.0 Library # Этот файл хранится в libraries/files.raml usage: | Use to define some basic file-related constructs. types: File: properties: name: type: string length: type: integer traits: drm: headers: drm-key: resourceTypes: file: get: is: drm put: is: drm После того, как библиотека сохранена в отдельном файле, к ней можно обращаться в основном файле спецификации:
#%RAML 1.0 title: Files API uses: files: !include libraries/files.raml resourceTypes: file: !include files-resource.raml /files: type: file Надстройки и расширения
Надстройки (overlays) и расширения (extensions) предназначены для кастомизации описаний API — например, когда требуется создать (и затем регулярно обновлять и поддерживать) документацию к API на нескольких языках. Задача эта не так проста, как может показаться на первый взгляд. Большинство имеющихся инструментов для документирования API не могут справиться с этой задачей без дополнительных «костылей».
В RAML 1.0 с помощью надстроек можно без проблем реализовать поддержку многоязычной документации. Представим, что у нас имеется документация к API на английском языке, и нам нужно сделать для неё французскую локализацию. Английская документация хранится в файле booklibrary.raml. Приведём небольшой фрагмент:
#%RAML 1.0 title: Book Library API documentation: - title: Introduction content: automated access to the books - title: Licensing content: Please respect the copyright on this book Чтобы добавить французскую локализацию, создадим файл-надстройку (overlay):
#%RAML 1.0 Overlay usage: French localisation masterRef: booklibrary.raml documentation: - title: Introduction content: l’accès automatisé aux livres - title: licenсe content: Respectez les droits d’auteur s.v.p. Этот файл включает только французские переводы; все описания методов и ответов при генерации будут взяты из основного файла.
C помощью расширений (extensions) можно создавать дополнительные описания методов и ответов. Это может понадобиться для адаптации описания API для разных категорий пользователей или для разных вариантов использования (например, в ситуации, когда пользователям бесплатной версии сервиса доступен базовый, а пользователям платной версии — расширенный набор функций),
Рассмотрим следующие фрагменты (примеры взяты отсюда):
Основной файл
#%RAML 1.0 title: Book Library API documentation: - title: Introduction content: Automated access to books - title: Licensing content: Please respect copyrights on our books. /books: description: The collection of library books get: Расширение с описанием функциональности API для пользователей с правами администратора
#%RAML 1.0 Extension usage: Add administrative functionality masterRef: librarybooks.raml /books: post: description: Add a new book to the collection Расширение для кастомной версии API, доступной по указанному URL
#%RAML 1.0 Extension usage: The location of the public instance of the Piedmont library API masterRef: librarybooks.raml baseUri: http://api.piedmont-library.com Заключение
Рассмотренные нами нововведения свидетельствуют о том, что RAML развивается в сторону простого, но в то же время очень гибкого языка описания, позволяющего документировать даже самые сложные API.
Радует и то, что сейчас появляются и новые, более совершенные инструменты для создания документации для API. Осенью 2015 года компания MuleSoft (основной разработчик RAML) выпустила плагин API WorkBench (см. также репозиторий на GitHub) для текстового редактора Atom — рекомендуем обратим внимание. Будем надеяться, что в дальнейшем этот инструмент будет успешно развиваться.
Если вы уже пользовались RAML 1.0 для документирования API, приглашаем поделиться опытом. Если вам кажется, что мы забыли рассказать о каком-то интересном нововведении — напишите нам, и мы обязательно добавим его в обзор.
Если вы по тем или иным причинам не можете оставлять комментарии здесь — добро пожаловать в наш корпоративный блог.
ссылка на оригинал статьи https://habrahabr.ru/post/281178/
Добавить комментарий