RAML 学习笔记
RAML,Swagger和API Blueprint区别
Swagger 优势在于对从现有的程序中自动生成接口,无需完全手写文档;
RAML 的优势是文档编写清晰方便,适合于没有现成接口,而需要全新规划;
Blueprint 的优点是 markdown 语法。因为目前手头的接口也是从 0 开始,也需要系统性的规划一下,因此选择 RAML 兼顾编写和规划
编辑器选择
VS code RAML 插件
学习记录
1. RAML文档头部声明
#%RAML 1.0
title: ZANE api
baseUri: http://api.zanezz.cn/{version}
version: v1
注意:raml的缩进是两空格
2. 资源定位
例如会员接口中包含了获取会员信息与新增一个会员两个接口方法,那么可以这样写资源定位:
/member:
description: the interface is operations about vip.
/getmember:
description: 获取会员信息,如果没有传入具体参数,则获取会员列表
/addmember:
description: 新增一个会员
注意每个冒号后面有一个空格,如果冒号后是 “|” 符号,则表示后面的内容是多行
3. 调用方法
那么接下来需要定义接口的调用方法,RESTful 标准中调用方法常用有 GET,POST,PUT,PATCH,DELETE。而这里我们常用的只有两种 GET 和 POST。其中 GET 主要用于读取操作,而 POST 主要用于写入操作。
/member:
description: the interface is operations about vip.
/getmember:
description: 获取会员信息,如果没有传入具体参数,则获取会员列表
get:
description: 获取会员信息,get方式
/addmember:
description: 新增一个会员
post:
description: 新增一个会员,post
4. 请求参数
有了调用方法还需要附上请求参数,如获取会员的参数是 mobile,而新增会员有 name 和 mobile 两个参数:
/member:
description: the interface is operations about vip.
/getmember:
description: 获取会员信息,如果没有传入具体参数,则获取会员列表
get:
description: 获取会员信息,get方式
queryParameters:
mobile:
/addmember:
description: 新增一个会员
post:
description: 新增一个会员,post
queryParameters:
name:
mobile:
接着对每个参数定义约束条件等,其中 type 表示参数类型,description 表示参数说明,required 表示是否必填:
/member:
description: the interface is operations about vip.
/getmember:
description: 获取会员信息,如果没有传入具体参数,则获取会员列表
get:
description: 获取会员信息,get方式
queryParameters:
mobile:
type: string
description: 会员电话
required: true
/addmember:
description: 新增一个会员
post:
description: 新增一个会员,post
queryParameters:
name:
type: string
description: 会员姓名
required: true
mobile:
type: string
description: 会员手机
required: true
5.返回结果
接下来还需要描述一下返回结果,结果中最好给出返回的示例,方便理解接口返回值,这里 reponses 表示返回结果定义,首先定义返回结果 200,定义 body,返回的格式 json,返回的示例 example:
#%RAML 1.0
title: ZANE api
baseUri: http://api.zanezz.cn/{version}
version: v1
/member:
description: the interface is operations about vip.
/getmember:
description: 获取会员信息,如果没有传入具体参数,则获取会员列表
get:
description: 获取会员信息,get方式
queryParameters:
mobile:
type: string
description: 会员电话
required: true
responses:
200:
body:
application/json:
example: |
{
"error":0,
"msg":"查询成功",
"data":[
{
"name":"王明",
"mobile":"12388888888"
},
{
"name":"zane",
"mobile":"15555255553"
}
]
/addmember:
description: 新增一个会员
post:
description: 新增一个会员,post
queryParameters:
name:
type: string
description: 会员姓名
required: true
mobile:
type: string
description: 会员手机
required: true