MSONはMarkdown Syntax for Object Notationの略で、プレインテキスト形式でAPIの仕様書を書くための言語です。
MSONの例
以下がMSONの例で、 /files に対するGETリクエストに関するAPI仕様書であることがわかります。200レスポンスのContent-typeはapplication/jsonで、pathというキーを持つオブジェクトの配列が返されることがわかります。
# GET /files
+ Response 200 (application/json)
+ Attributes (array, fixed-type)
+ (object)
+ path: `/files` (required)
型宣言
MSONでは型を宣言して再利用することができます。例えば以下はFileという型とPermissionという列挙型(enum)を宣言している例です。型宣言は Data Structures ブロックで行います。
# My API
## GET /files
+ Response 200 (application/json)
+ Attributes (array[File], fixed-type)
## Data Structures
### File (object)
+ name: `index.html`
+ size: 5012 (number)
+ `created_at`: `2007-04-05T24:00` (string)
+ permissions (Permission)
### Permission (enum)
+ r (default) - Read only
+ rw - Read-write
型
MSONで使える型を紹介します。
Object
キーとバリューのペアからなる型です。プロパティはデフォルトでoptional(省略可能)で、バリューの方は文字列です。特定のキーが確実に存在することを示すためにはrequiredというキーワードを使います。
+ name: API Blueprint (required)
また、値がnullになる可能性があることを示すためにはnullableキーワードを使います。
+ date (required, nullable)
さらに、fixedキーワードを使うとバリューが特定の値になっていることを示します。例えば以下の例ではtypeというキーに対応するバリューはadminであることをしましています。
+ type: admin (fixed)
配列
これは文字列もしくは数値を含む配列を宣言している例です。
+ Attributes (array[string, number], fixed-type)
具体例を表すためにはこのようにします。
+ Attributes (array, fixed-type)
+ 10 GBP
+ 20 GBP
+ 12.99 (number)
列挙型
特定のリストの中の値のみを取ることを表すために列挙型(enum)を使うこともできます。
## Direction (enum)
+ north
+ east
+ south
+ west
出展:
https://apiblueprint.org/documentation/mson/specification.html