RAML基础入门学习笔记

发表于 | 分类于 |

最近在对开发的系统功能进行服务化与接口化，将现有的功能逐渐转移至接口。这样一方面方便多系统之间相互调用，同时与外部团队协作开发也容易对接。这就遇到了问题，接口增多无论是自己使用，还是对接沟通，没有文档的话都需要消耗大量的时间去回顾，沟通。这时需求就出现了，需要一个接口文档维护工具。

发现RAML

最早采用的是网友开发的基于PHP的接口管理系统ApiManager，命名是很容易理解的。系统从安装到界面来说都很不错，小型的文档需求可以采用这个系统。而后在无意中了解到了网络上还有三大接口管理神器，分别是Swagger，RAML，API Blueprint，顿时就不淡定了。对一切新鲜事物感兴趣的性格上来，立刻着手去了解和使用。

三者的区别不详细说了，我个人简单的理解是Swagger优势在于对从现有的程序中自动生成接口，无需完全手写文档；RAML的优势是文档编写清晰方便，适合于没有现成接口，而需要全新规划；Blueprint的优点是markdown语法。因为目前手头的接口也是从0开始，也需要系统性的规划一下，因此选择RAML兼顾编写和规划。

用前准备

RAML只是一种文档编写标准格式，具体的编写方式和呈现形式可以根据需要自行选择对应的工具。工具这点来说其实不如Swagger丰富，但也基本够用。

编辑器选择

其实官网有对应的API Designer，API Console等工具，也有我喜欢的Sublime插件。因此编辑器前期选择在Sublime里安装对应的插件RAML Syntax Highlighter，安装好之后使用sublime开始编辑。

文档展现方式选择

最基础的展现方式是使用RAML2HTML将RAML文档转换为静态HTML，放置在网站中供需要的人浏览。而我发现RAML2HTML for PHP更加简单易用。这个PHP脚本通过解析RAML配合模板，实现一个动态的解析文档站。修改文档内容只需要修改对应的RAML文件内容即可。

基础学习记录

其实最基础的教程看官网的RAML 100 Tutorial就足够了。然后初学者加上对英文的些许担忧，会先着手找对应的中文教程。这里我就根据我的需求记录一下我的学习。

RAML文档头部声明

RAML文档头部有一个全局声明，基本包含的信息包括接口标题，接口的根url路径，接口版本等，一般看起来的头部是这样的：

1
2
3
4
#%RAML 0.8
title: KTSee API
baseUri: http://api.ktsee.com/{version}
version: v1

注意缩进占位符是2个空格，缩进在RAML语法中是相当重要的，一定不要多或者少了空格。这让我想起了python。

资源定位

资源定位其实是RESTful中的概念，然而公司的接口思路采用的是JSON-RPC，这里的资源定位可能不一样是指资源，也可能是方法的定位。例如会员接口中包含了获取会员信息与新增一个会员两个接口方法，那么可以这样写资源定位:

1
2
3
/member:
  /getmember:
  /addmember:

这样表示存在两个接口，分别是

  • 获取会员信息：http://api.ktsee.com/member/getmember
  • 新增一个会员：http://api.ktsee.com/member/addmember

你可以对每个接口添加描述文字，说明这些接口分别是做什么的

1
2
3
4
5
6
7
8
/member:
  description: 会员操作相关接口
  /getmember:
	description: |
	  获取会员信息，
	  该方法如果没有传入具体参数，则获取会员列表
  /addmember:
	description: 新增一个会员
注意每个冒号后面有一个空格，如果冒号后是“ ”符号，则表示后面的内容是多行

调用方法

上面定义了接口，那么接下来需要定义接口的调用方法，RESTful标准中调用方法常用有GET，POST，PUT，PATCH，DELETE。而这里我们常用的只有两种GET和POST。其中GET主要用于读取操作，而POST主要用于写入操作。

上面的例子，获取会员信息getmember是读操作，而新增一个会员是写操作，因此这样定义调用方法：

1
2
3
4
5
6
7
8
9
10
11
12
13
/member:
  description: 会员操作相关接口
  /getmember:
	description: |
	  获取会员信息，
	  该方法如果没有传入具体参数，则获取会员列表
	get:
	  description: 获取会员信息，GET方式

  /addmember:
	description: 新增一个会员
	post:
	  description: 新增一个会员，POST方式

get和post由于在RESTful中对应不同的方法，所以也会有相应的描述，这里我们也可以不写这部分描述

请求参数

有了调用方法还需要附上请求参数，如获取会员的参数是mobile，而新增会员有name和mobile两个参数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/member:
  description: 会员操作相关接口
  /getmember:
	description: |
	  获取会员信息，
	  该方法如果没有传入具体参数，则获取会员列表
	get:
	  description: 获取会员信息，GET方式
	  queryParameters: 
	    mobile:
	  
  /addmember:
	description: 新增一个会员
	post:
	  description: 新增一个会员，POST方式
	  queryParameters: 
		name:
		mobile:

接着对每个参数定义约束条件等，其中type表示参数类型，description表示参数说明，required表示是否必填：

1
2
3
4
5
6
7
8
9
10
11
12
13
  /addmember:
	description: 新增一个会员
	post:
	  description: 新增一个会员，POST方式
	  queryParameters: 
		name:
		  type: string
		  description: 会员姓名
		  required: true
		mobile:
		  type: string
		  description: 会员手机
		  required: true

返回结果

接下来还需要描述一下返回结果，结果中最好给出返回的示例，方便理解接口返回值，这里reponses表示返回结果定义，首先定义返回结果200，定义body，返回的格式json，返回的示例example：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
/member:
  description: 会员操作相关接口
  /getmember:
	description: |
	  获取会员信息，
	  该方法如果没有传入具体参数，则获取会员列表
	get:
	  description: 获取会员信息，GET方式
	  queryParameters:
		mobile:
		  type: string
		  description: 会员手机
		  required: true
	  responses:
		200:
		  body:
			application/json:
			  example: |
				{
				  "error": 0,
				  "msg": "查询成功",
				  "data": [
					{
					  "name": "王明",
					  "mobile": "13888888888"
					},
					{
					  "name": "李四",
					  "mobile": "13999999999"
					}
				  ]
				}

结果展示

RAML2HTML for PHP展示效果

坚持原创技术分享，您的支持将鼓励我继续创作！