使用RAML描述API文档信息的一些用法整理

时间:2021-09-11 06:01:04

RAML是Restful API Modeling Language的缩写,是用来描述API信息的文档。

创建一个.raml后缀的文件,用Atom打开。

基本用法

#%RAML 0.8
title: Book API
baseUri: http://api.book.com/{version}
version: v1
/users:
/authors:
/{authorname}:
/books:
get:
queryParameters:
author:
displayName: Author
type: string
description: An author's full name
example: Mary
required: false
publicationYear:
displayName: Pub Year
type: number
description: The year released for the first time
example: 1984
required: false
rating:
displayName: Rating
type: number
description: Average rating
required: false
isBn:
displayName: ISBN
type: string
minLength: 10
example: 0321736079
put:
queryParameters:
access_token:
displayName: Access Token
type: string
description: Token giving you permission to make call
required: true
post:
/{bookTitle}:
get:
description: Retrieve a specific book title
responses:
200:
body:
application/json:
example: |
{
"data":{
"id": "SbBGk",
"title": "its the title",
"descritpion": null
},
"success": true,
"status": 200
} put:
delete:
/author:
get:
/publiser:
get:

以上,

● 类型/users:看作是resource,也就是以/开始,:结尾,而且resource是嵌套存在的
● queryParameters描述查询字符串

接下来把.raml转换成html格式,有一个开源的项目。

→ 参考:https://github.com/raml2html/raml2html
→ 全局安装:npm i -g raml2html
→ .raml文件所在文件夹内打开命令窗口,输入:raml2html example.raml > example.html

就是这么个效果:

使用RAML描述API文档信息的一些用法整理

Body Parameters

POST请求,通常把参数放到body中传递,在RAML中如何描述呢?

在Body中的参数传递有很多方式,需要在Headers下的Content-Type中设置。Content-Type这个key可能的值包括:multipart/form-data, application/json, application/x-www-form-urlencoded等等。

1、通过multipart/form-data

/file-content:
description: The file to be reproduced by the client
get:
description: Get the file content
responses:
200:
body:
binary/octet-stream:
example:
!include heybulldog.mp3
post:
description: |
Enters the file content for an existing song entity. Use the "binary/octet-stream" content type to specify the content from any consumer (excepting web-browsers).
Use the "multipart-form/data" content type to upload a file which content will become the file-content
body:
binary/octet-stream:
multipart/form-data:
formParameters:
file:
description: The file to be uploaded
required: true
type: file

以上,

● Content-Type能接受的类型是binary/octet-stream或multipart/form-data
● 对于multipart/form-data类型,键值数据放在了formParameters中
● !include heybulldog.mp3表示把heybulldog.mp3文件引入进来

2、通过JSON Shema

JSON Shema用来描述JSON格式。

为什么需要JSON Schema呢?

举个例子:

{
"id":1,
"name":"a green door",
"price":12.50,
"tags":["home", "green"]
}

我们可能会问:

● 什么是id
● name字段必须吗
● price的值可以是0吗
● tags所代表的数组元素是string类型吗?

JSON Schema就是解决这些问题的。

{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object"
}

以上,

● $schema表示当前JSON Shema所采用的版本
● type字段是必须的,是object类型

接着,对id字段约束。

{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for a product",
"type": "integer"
}
},
"required": ["id"]
}

对name字段约束。

{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for a product",
"type": "integer"
},
"name": {
"description": "Name of the product",
"type": "string"
}
},
"required": ["id", "name"]
}

对price字段约束。

{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for a product",
"type": "integer"
},
"name": {
"description": "Name of the product",
"type": "string"
},
"price": {
"type": "number",
"minimum": 0,
"exclusiveMinimum": true
}
},
"required": ["id", "name", "price"]
}

对tags字段约束。

{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for a product",
"type": "integer"
},
"name": {
"description": "Name of the product",
"type": "string"
},
"price": {
"type": "number",
"minimum": 0,
"exclusiveMinimum": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
}
},
"required": ["id", "name", "price"]
}

数组如何用JSON Schema描述呢?

[
{
"id": 2,
"name": "An ice sculpture",
"price": 12.50,
"tags": ["cold", "ice"],
"dimensions": {
"length": 7.0,
"width": 12.0,
"height": 9.5
},
"warehouseLocation": {
"latitude": -78.75,
"longitude": 20.4
}
},
{
"id": 3,
"name": "A blue mouse",
"price": 25.50,
"dimensions": {
"length": 3.1,
"width": 1.0,
"height": 1.0
},
"warehouseLocation": {
"latitude": 54.4,
"longitude": -32.7
}
}
]

用JSON Shema描述就是这样:

{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product set",
"type": "array",
"items": {
"title": "Product",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for a product",
"type": "number"
},
"name": {
"type": "string"
},
"price": {
"type": "number",
"minimum": 0,
"exclusiveMinimum": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
},
"dimensions": {
"type": "object",
"properties": {
"length": {"type": "number"},
"width": {"type": "number"},
"height": {"type": "number"}
},
"required": ["length", "width", "height"]
},
"warehouseLocation": {
"description": "Coordinates of the warehouse with the product",
"$ref": "http://json-schema.org/geo"
}
},
"required": ["id", "name", "price"]
}
}

RAML也用到了JSON Shema,就像这样:

body:
application/json:
schema: |
{
"type": "object",
"$schema": "http://json-schema.org/draft-03/schema",
"id": "http://jsonschema.net",
"required": true,
"properties": {
"songTitle": {
"type": "string",
"required": true
},
"albumId": {
"type": "string",
"required": true,
"minLength": 36,
"maxLength": 36
}
}
}
example: |
{
"songId": "550e8400-e29b-41d4-a716-446655440000",
"songTitle": "Get Lucky",
"albumId": "183100e3-0e2b-4404-a716-66104d440550"
}

schemas

每个资源都有自己的schema,是否可以把所有资源的schema合并到同一个地方呢?

RAML提供了schemas字段。

schemas:
- song: |
{
"type": "object",
"$schema": "http://json-schema.org/draft-03/schema",
"id": "http://jsonschema.net",
"required": true,
"properties": {
"songTitle": {
"type": "string",
"required": true
},
"albumId": {
"type": "string",
"required": true,
"minLength": 36,
"maxLength": 36
}
}
}

按如下引用:

body:
application/json:
schema: song
example: |
{
"songId": "550e8400-e29b-41d4-a716-446655440000",
"songTitle": "Get Lucky",
"albumId": "183100e3-0e2b-4404-a716-66104d440550"
}

Resource Types资源类型

每个资源通有相似的部分,能否把这些相似的部分提取抽象出来呢?

假设有2个资源:/resources和/{resourceId}

#%RAML 0.8
title: /resources:
get:
post:
/{resourceId}:
get:
put:
delete:

以上,resource大致可以分成针对集合和针对个体的,所以,在RAML中通过resourceTypes对资源进行分类,有这样的表达方式:

resourceTypes:
- collection:
get:
post:
- collection-item:
get:

于是collection类型可以写成这样:

resourceTypes:
- collection:
description: Collection of available <<resourcePathName>> in Jukebox.
get:
description: Get a list of <<resourcePathName>>.
responses:
200:
body:
application/json:
post:
description: |
Add a new <<resourcePathName|!singularize>> to Jukebox.
queryParameters:
access_token:
description: "The access token provided by the authentication application"
example: AABBCCDD
required: true
type: string
body:
application/json:
schema: <<resourcePathName|!singularize>>
responses:
200:
body:
application/json:
example: |
{ "message": "The <<resourcePathName|!singularize>> has been properly entered" }

以上,

● <<resourcePathName>>是占位符,类似表示songs
● 另外<<resourcePath>>是占位符,类似表示/songs
● <<resourcePathName|!singularize>>是占位符,类似表示song

● <<resourcePathName|!pluralize>>是占位符,类似表示songs

然后这样使用:

/songs:
type: collection
get:
queryParameters:
songTitle:
description: "The title of the song to search (it is case insensitive and doesn't need to match the whole title)"
required: true
minLength: 3
type: string
example: "Get L"
responses:
200:
body:
application/json:
example: |
"songs": [
{
"songId": "550e8400-e29b-41d4-a716-446655440000",
"songTitle": "Get Lucky"
},
{
"songId": "550e8400-e29b-41d4-a716-446655440111",
"songTitle": "Loose yourself to dance"
},
{
"songId": "550e8400-e29b-41d4-a716-446655440222",
"songTitle": "Gio sorgio by Moroder"
}
]
post:
body:
application/json:
example: |
{
"songId": "550e8400-e29b-41d4-a716-446655440000",
"songTitle": "Get Lucky",
"albumId": "183100e3-0e2b-4404-a716-66104d440550"
}

collection-item类型可以写成这样:

resourceTypes:
- collection:
... - collection-item:
description: Entity representing a <<resourcePathName|!singularize>>
get:
description: |
Get the <<resourcePathName|!singularize>>
with <<resourcePathName|!singularize>>Id =
{<<resourcePathName|!singularize>>Id}
responses:
200:
body:
application/json:
404:
body:
application/json:
example: |
{"message": "<<resourcePathName|!singularize>> not found" }

然后这样使用:

/songs:
...
/{songId}:
type: collection-item
get:
responses:
200:
body:
application/json:
example: |
{
"songId": "550e8400-e29b-41d4-a716-446655440000",
"songTitle": "Get Lucky",
"duration": "6:07",
"artist": {
"artistId": "110e8300-e32b-41d4-a716-664400445500"
"artistName": "Daft Punk",
"imageURL": "http://travelhymns.com/wp-content/uploads/2013/06/random-access-memories1.jpg"
},
"album": {
"albumId": "183100e3-0e2b-4404-a716-66104d440550",
"albumName": "Random Access Memories",
"imageURL": "http://upload.wikimedia.org/wikipedia/en/a/a7/Random_Access_Memories.jpg"
}
}

以上,
● 在resourceTypes中的谓词get,post等,可以在具体的resource中进行重新定义
● 在resrouce级别,通过type: collection-item或type: collection与resourceTypes对应

Parameters

以上,resourceTypes字段所代表的是一个对集合和个体类型相同操作的一个封装,在这些操作中,在这些请求响应中,有时需要通过example字段来举例,通常这样写:

example: |
{
...
} 或者 example: |
[
{ },
{ }
]

但在RAML中,为我们提供了<<exampleCollection>>和<<exampleItem>>占位符分别表示集合和个体。

resourceTypes:
- collection:
description: Collection of available <<resourcePathName>> in Jukebox.
get:
description: Get a list of <<resourcePathName>>.
responses:
200:
body:
application/json:
example: |
<<exampleCollection>>
post:
description: |
Add a new <<resourcePathName|!singularize>> to Jukebox.
queryParameters:
access_token:
description: "The access token provided by the authentication application"
example: AABBCCDD
required: true
type: string
body:
application/json:
schema: <<resourcePathName|!singularize>>
example: |
<<exampleItem>>
responses:
200:
body:
application/json:
example: |
{ "message": "The <<resourcePathName|!singularize>> has been properly entered" }
- collection-item:
description: Entity representing a <<resourcePathName|!singularize>>
get:
description: |
Get the <<resourcePathName|!singularize>>
with <<resourcePathName|!singularize>>Id =
{<<resourcePathName|!singularize>>Id}
responses:
200:
body:
application/json:
example: |
<<exampleItem>>
404:
body:
application/json:
example: |
{"message": "<<resourcePathName|!singularize>> not found" }

在资源resource部分通常这样调用:

/songs:
type:
collection:
exampleCollection: |
[
...
]
/{songId}:
type:
collection-item:
exampleItem: |
{
...
}

具体来说,类似这样:

/songs:
type:
collection:
exampleCollection: |
[
{
"songId": "550e8400-e29b-41d4-a716-446655440000",
"songTitle": "Get Lucky"
},
{
"songId": "550e8400-e29b-41d4-a716-446655440111",
"songTitle": "Loose yourself to dance"
},
{
"songId": "550e8400-e29b-41d4-a716-446655440222",
"songTitle": "Gio sorgio by Morodera"
}
]
exampleItem: |
{
"songId": "550e8400-e29b-41d4-a716-446655440000",
"songTitle": "Get Lucky",
"albumId": "183100e3-0e2b-4404-a716-66104d440550"
}
get:
queryParameters:
songTitle:
description: "The title of the song to search (it is case insensitive and doesn't need to match the whole title)"
required: true
minLength: 3
type: string
example: "Get L"
/{songId}:
type:
collection-item:
exampleItem: |
{
"songId": "550e8400-e29b-41d4-a716-446655440000",
"songTitle": "Get Lucky",
"duration": "6:07",
"artist": {
"artistId": "110e8300-e32b-41d4-a716-664400445500"
"artistName": "Daft Punk",
"imageURL": "http://travelhymns.com/wp-content/uploads/2013/06/random-access-memories1.jpg"
},
"album": {
"albumId": "183100e3-0e2b-4404-a716-66104d440550",
"albumName": "Random Access Memories",
"imageURL": "http://upload.wikimedia.org/wikipedia/en/a/a7/Random_Access_Memories.jpg"
}
}

Includes

可以把一些example放到单独的文件,然后通过!include关键字来引用这些文件。

/songs:
type:
collection:
exampleCollection: !include jukebox-include-songs.sample
exampleItem: !include jukebox-include-song-new.sample
/{songId}:
type:
collection-item:
exampleItem: !include jukebox-include-song-retrieve.sample

traits

如何描述查询、排序、分页呢?

traits:
- searchable:
queryParameters:
query:
description: |
JSON array [{"field1","value1","operator1"},{"field2","value2","operator2"},...,{"fieldN","valueN","operatorN"}] <<description>>
example: |
<<example>>aml - orderable:
queryParameters:
orderBy:
description: |
Order by field: <<fieldsList>>
type: string
required: false
order:
description: Order
enum: [desc, asc]
default: desc
required: false
- pageable:
queryParameters:
offset:
description: Skip over a number of elements by specifying an offset value for the query
type: integer
required: false
example: 20
default: 0
limit:
description: Limit the number of elements on the response
type: integer
required: false
example: 80
default: 10

按如下使用这些trait。

/songs:
type:
collection:
exampleCollection: !include jukebox-include-songs.sample
exampleItem: !include jukebox-include-song-new.sample
get:
is: [
searchable: {description: "with valid searchable fields: songTitle", example: "[\"songTitle\", \"Get L\", \"like\"]"},
orderable: {fieldsList: "songTitle"},
pageable
]

另外,schema也可以放到单独的文件中,然后通过!include引用。

schemas:
- song: !include jukebox-include-song.schema
- artist: !include jukebox-include-artist.schema
- album: !include jukebox-include-album.schema

resourceTypes也可以放到单独的文件中:

resourceTypes: !include jukebox-includes-resourceTypes.inc