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
