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