RAML是什么呢?

下面这段话摘自于网络

RAML的全称是RESTful API建模语言，这是一种基于YAML格式的新规范，因此机器与人类都能够轻易地理解其中的内容。但RAML的目的不仅仅在于创建更易于理解的规范（你可以将这一工作指派给文档团队，他们会做得更好）而已。RAML的设计者Uri Sarid希望使用者能够打破固有的思维，在开始编写代码之前以一种全新的方式对API进行建模。

它的官网是:

http://raml.org/

虽然目前国内没有太多这方面的资料,国外也是不温不火的,但是围绕着raml已经建立起了一个小的生态,涵盖了API的全部生命周期,从设计到构建,从测试到文档

raml是和具体开发语言无关的,但是需要依赖具体的第三方工具来提供相应的服务,目前对于nodejs,python,java,php等语言均支持的不错,本人以nodejs为例进行学习.

先看一下语法

#%RAML 0.8
title: Remote Medicine Example API
mediaType: application/json
/cases:
  description: The urgent cases created by the remote medicine partner
  get:
    description: Get a list of cases
    queryParameters:
      startFrom:
        type: number
        description: The number of the first question, where 0 means latest
        default: 0
      numberToReturn:
        type: number
        description: How many questions to return
        default: 5
    responses:
      200:
        body:
          example: |
            {
              "totalNumber": 3781,
              "cases":
              [
                {
                  "id": "c68732",
                  "overview": "The patient just collapsed",
                  "location": "Oro Valley",
                  "created": "Sat, 24 May 2014 23:18:01 GMT"
                },
                {
                  "id": "c98729",
                  "overview": "The patient felt severe headaches and saw flashes",
                  "location": "Picacho Peak",
                  "created": "Fri, 25 Apr 2014 04:34:00 GMT"
                }
              ]
            }

和yaml是不是很像?而且看起来很简单?

接下来介绍一下他的编辑器

• API-wordkbench
• API-Design

API-workbench是基于atom的插件,支持raml语法和实时预览

http://apiworkbench.com/

API-Design是一个基于nodejs的web编辑器,需要自己部署服务端

https://github.com/mulesoft/api-designer

而我选择了API-workbench

API-workbench

图中为示例代码,可以在下面的url中拿到

http://static-anypoint-mulesoft-com.s3.amazonaws.com/API_examples_notebooks/raml-design3.html

生成mock服务

这里用到的工具是Osprey Mock Service:

https://github.com/mulesoft-labs/osprey-mock-service

使用方法

npm install -g osprey-mock-service
osprey-mock-service -f api.raml -p 8000

这里api.raml是上一步中生成的raml文件
接下来访问 http://localhost:8000/cases,就有模拟的输出了

实现API

接下来本应该是编码实现的,但是为了快速感受raml的特点,此步骤略过,由mock服务代替

测试

测试用的工具有多重选择,选择了相对比较流行的Abao工具,工具可以在下面找到

https://github.com/cybertk/abao/

使用方法

npm install -g abao
abao api.yaml  --server http://localhost:8080

如果api.yaml中提供了baseUrl属性的话,也可以不指定--server属性

微信截图_20170211174744.png

免责声明

本文为初次学习笔记,对于多处均略过,如果有不对的地方,请留言指正.