RESTful APIの記述に使用されるマークアップ言語であるRAMLについてはすでに書いています。 Habrahabrに関する記事の議論の中で、読者の1人は、RAMLが2014年の夏以降ほとんど更新されていないことに気付きました。
数か月間、RAML形式は大幅に改善されました。 新しい仕様バージョン1.0は、比較的最近、2015年10月上旬に公式Webサイトで公開されました。 前のバージョン（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パラメーター、ヘッダー、クエリパラメーターの説明で使用できます。
/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エンドポイントの1つが実験的としてマークされます。
アノテーションは、より複雑な状況でも使用できます。たとえば、テストケースを説明する場合などです。
#%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のもう1つの革新はライブラリです。 ライブラリは、プロファイル、データ型、およびその他の情報がドキュメントの導入部分に配置されているファイルです。 新しいドキュメントでは、導入部分を詳細に描くことはできませんが、既存のライブラリを参照できます。 この方法は、プログラムコードで外部ライブラリとモジュールを接続することを連想させます。
ライブラリの例を次に示します。
#%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
アドオンと拡張機能
アドオン（オーバーレイ）および拡張機能（拡張機能）は、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
フランス語のローカライズを追加するには、オーバーレイファイルを作成します。
#%RAML 1.0 Overlay usage: French localisation masterRef: booklibrary.raml documentation: - title: Introduction content: l'accès automatisé aux livres - title: licene content: Respectez les droits d'auteur svp
このファイルにはフランス語の翻訳のみが含まれています。 生成中のメソッドと回答のすべての説明は、メインファイルから取得されます。
拡張機能を使用すると、メソッドと応答の追加の説明を作成できます。 これは、さまざまなユーザーカテゴリまたはさまざまなユースケースに合わせて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
指定されたURLで利用可能なAPIのカスタムバージョンの拡張機能
#%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のドキュメントを作成するための新しい高度なツールが追加されました。 2015年の秋に、MuleSoft（RAMLのメイン開発者）は、 Atomテキストエディター用のWorkBench APIプラグイン （ GitHubリポジトリも参照）をリリースしました -注意することをお勧めします。 将来、このツールが正常に開発されることを期待しましょう。
既にRAML 1.0を使用してAPIのドキュメントを作成している場合は、経験を共有してください。 興味深い革新についてお話しするのを忘れたと思われる場合は、ご連絡ください。間違いなくレビューに追加します。
何らかの理由でここにコメントを残せない場合は、当社の企業ブログへようこそ。