Raml实践

Raml实践

简介：RAML的全称是RESTful API Modeling Language，这是一种用来描述基于Restful架构的API（设计API）的语言。它的语法规范是基于YAML的新规范，因此机器与人类都能够轻易地理解其中的内容。

一、工具安装

---

一、API Workbench（客户端工具-推荐）

介绍：

API Workbench是一个丰富的全功能集成开发环境（IDE），用于设计，构建，测试，记录和共享RESTful HTTP API。
它支持RAML 0.8和最近启动的RAML 1.0。 
RAML使得易于管理从设计到共享的整个API生命周期。

安装：

1.安装Atom

2.在Setting->Install栏目，搜索并安装api-workbench

3.在Setting->Packages中可以看到已安装的api-workbench

---

二、API Designer（Web工具）

介绍：

由MuleSoft开发的基于RAML的Web工具，专门用于创建和分享API标准的web编辑器。
它能提示在什么地方应该使用什么元素以及指出创建的RAML文档中的错误。

安装：

1.安装Nodejs

2.通过npm安装模块

npm install -g api-designer

3.运行命令

api-designer

---

三、raml2html

介绍：

把.raml转换成html格式便于查看

安装：

1.安装nodejs

2.通过npm安装模块

npm install -g raml2html

3.运行命令
raml2html api.raml > api.html
4.预览图

二、Raml语法

根节点元素汇总

---

1.documentation

可选文档节点包括作为API的用户指南和参考文档的各种文档。这些文件可以阐明API如何工作或提供技术和业务环境。

文档节点的值是一个或多个文档的序列。每个文档都是一个映射，必须在下面的表中有两个键值对：

名称	描述
title	文件标题。它的值必须是非空字符串。
content	文件内容。它的值必须是一个非空字符串，可以使用Markdown格式。

举例：

#%RAML 1.0
title: ZEncoder API
baseUri: https://app.zencoder.com/api
documentation:
 - title: Home
   content: |
     Welcome to the _Zencoder API_ Documentation. The _Zencoder API_
     allows you to connect your application to our encoding service
     and encode videos without going through the web  interface. You
     may also benefit from one of our
     [integration libraries](https://app.zencoder.com/docs/faq/basics/libraries)
     for different languages.
 - title: Legal
   content: kkkkkkk

效果：

1

---

2.Base URI and Base URI Parameters

可选的baseuri节点指定一个URI作为标识符的API作为一个整体，并可用于指定URL的API服务（服务终端），构成它的每个资源的URL的基础。该baseuri节点的值是一个字符串，必须符合规范或模板rfc2396 URI的URI。

距离：

#%RAML 1.0
title: Amazon S3 REST API
version: 1
baseUri: https://{bucketName}.s3.amazonaws.com
baseUriParameters:
  bucketName:
    description: The name of the bucket

效果：

---

3.Protocols

可选协议节点指定API支持的协议。如果协议节点没有明确规定，在baseuri节点包含一个或多个协议使用；如果协议是显式指定的节点，节点规范凌驾于任何协议包括在baseuri节点。该协议的节点必须是一个非空的字符串数组，值的HTTP或HTTPS，并是不区分大小写。

下面是一个例子，一个API端点接收HTTP和HTTPS请求。

举例：

#%RAML 1.0
title: Salesforce Chatter REST API
version: v28.0
protocols: [ HTTP, HTTPS ]
baseUri: https://na1.salesforce.com/services/data/{version}/chatter

---

4.Default Media Types