raml php,RAML 学习笔记

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