RAML基础入门学习笔记

Web开发 2016-08-25

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

发现RAML

最早采用的是网友开发的基于PHP的接口管理系统ApiManager,命名是很容易理解的。系统从安装到界面来说都很不错,小型的文档需求可以采用这个系统。而后在无意中了解到了网络上还有三大接口管理神器,分别是SwaggerRAMLAPI 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路径,接口版本等,一般看起来的头部是这样的:

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

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

资源定位

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

/member:
  /getmember:
  /addmember:

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

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

/member:
  description: 会员操作相关接口
  /getmember:
    description: |
      获取会员信息,
      该方法如果没有传入具体参数,则获取会员列表
  /addmember:
    description: 新增一个会员

注意每个冒号后面有一个空格,如果冒号后是“|”符号,则表示后面的内容是多行

调用方法

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

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

/member:
  description: 会员操作相关接口
  /getmember:
    description: |
      获取会员信息,
      该方法如果没有传入具体参数,则获取会员列表
    get:
      description: 获取会员信息,GET方式

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

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

请求参数

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

/member:
  description: 会员操作相关接口
  /getmember:
    description: |
      获取会员信息,
      该方法如果没有传入具体参数,则获取会员列表
    get:
      description: 获取会员信息,GET方式
      queryParameters: 
        mobile:
      
  /addmember:
    description: 新增一个会员
    post:
      description: 新增一个会员,POST方式
      queryParameters: 
        name:
        mobile:

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

  /addmember:
    description: 新增一个会员
    post:
      description: 新增一个会员,POST方式
      queryParameters: 
        name:
          type: string
          description: 会员姓名
          required: true
        mobile:
          type: string
          description: 会员手机
          required: true

返回结果

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

/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展示效果


本文由 surenkid 创作,采用 知识共享署名 3.0,可自由转载、引用,但需署名作者且注明文章出处。

2 条评论

  1. 213213
    213213

  2. antMomo
    antMomo

    感謝 ! 寫的非常清楚

添加新评论