前言
RAML:
RAML的全称是RESTful API Modeling Language(RESTful API建模语言),这是一种基于YAML格式的新规范,书写格式和YAML相同。RAML官网
设计API
-
设计一个企业员工信息API,可以获取企业员工的个人信息。进入Design Center
-
首先撰写API的基本信息
#%RAML 1.0
title: EmployeeAPI
documentation:
- title: 个人信息
content: |
个人信息,可以通过访问接口获取员工的个人信息
标签 | 作用 |
---|---|
#%RAML x.x | 指定RAML版本 |
title | API名 |
documentation | 为API撰写文档 |
-title | 文档标题 |
content | 文档内容 |
- API返回值类型
types:
employee:
type: object
properties:
number:
type: string
displayName: "员工号"
pattern: "[0-9]{8}"
example: "12345678"
name:
type: string
displayName: "员工姓名"
description: "员工姓名只能是大小写字母"
required: true
maxLength: 20
minLength: 2
pattern: "[a-zA-Z]{2,20}"
example: "zhangsan"
age:
type: string
displayName: "员工年龄"
pattern: "[0-9]{1,2}"
example: "20"
sex:
type: string
displayName: "员工性别"
enum:
- man
- woman
example: "man"
phone:
type: string
displayName: "员工电话"
pattern: "[0-9]{11}"
example: "12345678901"
Email:
type: string
displayName: "电子邮箱"
pattern: "[\\w]+(\\.[\\w]+)*@[\\w]+(\\.[\\w]+)"
example: "san.b.zhang@acc.com"
state:
type: string
displayName: "居住省市"
pattern: "[a-zA-Z]{1,20}"
example: "liaoning"
city:
type: string
displayName: "居住城市"
pattern: "[a-zA-Z]{1,20}"
example: "dalian"
group:
type: string
displayName: "项目名"
pattern: "[a-zA-Z]{1,20}"
example: "afl"
team:
type: string
displayName: "组名"
pattern: "[a-zA-Z]{1,20}"
example: "mulesoft"
Enumber:
properties:
number:
type: string
displayName: "员工号"
pattern: "[0-9]{8}"
example: "12345678"
标签 | 作用 |
---|---|
types | 设置类型标识符 |
employee | 类名设置为employee(可自定义) |
type | 类型,值可以为(any,array,boolean,datetime…,file,integer,number,object,string,自定义类型) |
properties | 变量名(为类设置变量) |
displayName | 为变量起一个容易理解的别名 |
description | 变量的描述内容 |
required | 必须或可选(true,false) |
maxLength | 最大长度 |
minLength | 最小长度 |
pattern | 正则表达式内容 |
example | 输出例子 |
enum | 枚举类型 |
- 定义接口
/getEmpInf:
get:
responses:
200:
body:
application/json:
type: employee[]
post:
body:
application/json:
type: Enumber
responses:
200:
body:
application/json:
type: employee
标签 | 作用 |
---|---|
/ | 路由 |
get | 请求方式 |
body | 外层为请求体,responses内为响应体 |
responses | 响应 |
200 | HTTP状态码 |
application/json | 消息格式 |
- Design Center内容
6.现在的employee可以进行拆解分类,比如电话和邮箱可以整合成联系方式类,居住省市和居住城市可以整合为地址类,整合后代码如下:
types:
employee:
type: object
properties:
number:
type: string
displayName: "员工号"
pattern: "[0-9]{8}"
example: "12345678"
name:
type: string
displayName: "员工姓名"
description: "员工姓名只能是大小写字母"
required: true
maxLength: 20
minLength: 2
pattern: "[a-zA-Z]{2,20}"
example: "zhangsan"
age:
type: string
displayName: "员工年龄"
pattern: "[0-9]{1,2}"
example: "20"
sex:
type: string
displayName: "员工性别"
enum:
- man
- woman
example: "man"
group:
type: string
displayName: "项目名"
pattern: "[a-zA-Z]{1,20}"
example: "afl"
team:
type: string
displayName: "组名"
pattern: "[a-zA-Z]{1,20}"
example: "mulesoft"
contact:
type: contact
displayName: "联系方式"
address:
type: address
displayName: "地址"
contact:
type: object
properties:
phone:
type: string
displayName: "员工电话"
pattern: "[0-9]{11}"
example: "12345678901"
Email:
type: string
displayName: "电子邮箱"
pattern: "[\\w]+(\\.[\\w]+)*@[\\w]+(\\.[\\w]+)"
example: "san.b.zhang@acc.com"
address:
type: object
properties:
state:
type: string
displayName: "居住省市"
pattern: "[a-zA-Z]{1,20}"
example: "liaoning"
city:
type: string
displayName: "居住城市"
pattern: "[a-zA-Z]{1,20}"
example: "dalian"
Enumber:
properties:
number:
type: string
displayName: "员工号"
pattern: "[0-9]{8}"
example: "12345678"
- Design Center支持设置单独的类文件,把types拆解分类为四个文件,分别为:employeeType.raml,contactType.raml,addressType.raml,EnumberType.raml
在EmployeeAPI中进行引用,这样分类方便管理,效果会更好
types:
employee: !include entity/employeeType.raml
Enumber: !include entity/EnumberType.raml
创建entity文件夹
按照如下步骤创建employeeType.raml,contactType.raml,addressType.raml,EnumberType.raml四个文件
- 创建文件
- 定义文件类型,选择文件类型为Data Type,为文件命名
- 代码如下
employeeType.raml:
#%RAML 1.0 DataType
type: object
properties:
number:
type: string
displayName: "员工号"
pattern: "[0-9]{8}"
example: "12345678"
name:
type: string
displayName: "员工姓名"
description: "员工姓名只能是大小写字母"
required: true
maxLength: 20
minLength: 2
pattern: "[a-zA-Z]{2,20}"
example: "zhangsan"
age:
type: string
displayName: "员工年龄"
pattern: "[0-9]{1,2}"
example: "20"
sex:
type: string
displayName: "员工性别"
enum:
- man
- woman
example: "man"
group:
type: string
displayName: "项目名"
pattern: "[a-zA-Z]{1,20}"
example: "afl"
team:
type: string
displayName: "组名"
pattern: "[a-zA-Z]{1,20}"
example: "mulesoft"
contact:
type: !include contactType.raml
displayName: "联系方式"
address:
type: !include addressType.raml
displayName: "地址"
contactType.raml:
#%RAML 1.0 DataType
type: object
properties:
phone:
type: string
displayName: "员工电话"
pattern: "[0-9]{11}"
example: "12345678901"
Email:
type: string
displayName: "电子邮箱"
pattern: "[\\w]+(\\.[\\w]+)*@[\\w]+(\\.[\\w]+)"
example: "san.b.zhang@acc.com"
addressType.raml:
#%RAML 1.0 DataType
type: object
properties:
state:
type: string
displayName: "居住省市"
pattern: "[a-zA-Z]{1,20}"
example: "liaoning"
city:
type: string
displayName: "居住城市"
pattern: "[a-zA-Z]{1,20}"
example: "dalian"
EnumberType.raml:
#%RAML 1.0 DataType
properties:
number:
type: string
displayName: "员工号"
pattern: "[0-9]{8}"
example: "12345678"
employeeapi.raml:
#%RAML 1.0
title: EmployeeAPI
documentation:
- title: 个人信息
content: |
个人信息,可以通过访问接口获取员工的个人信息
types:
employee: !include entity/employeeType.raml
Enumber: !include entity/EnumberType.raml
/getEmpInf:
get:
responses:
200:
body:
application/json:
type: employee[]
post:
body:
application/json:
type: Enumber
responses:
200:
body:
application/json:
type: employee
完成后如图:
下回介绍测试接口