MuleSoft系列(三)- 使用API设计器通过RAML定义API

在MuleSoft中,创建Application的方式有三种

  • Flow Designer:用于构建连接系统并使用API的集成应用程序的Web应用程序
  • API Designer:用于设计,记录和模拟API的Web应用
  • Anypoint Studio:桌面IDE,用于实现API和构建集成应用程序

那么来看看如何使用API Designer 设计API并进行测试

在Anypoint Platform中,进入Design Center,点击Create New,在弹出框中选择 Create API Specification,输入名称:GetPerson,其他保持默认选择,点击创建

MuleSoft系列(三)- 使用API设计器通过RAML定义API

来看看进入的编辑页面,主要包括左侧的文档区域,右侧的API控制台,中间部分是编辑区域,底部有关键词提示区域,在MuleSoft中被称为Shelf

API Designer主要帮助我们编写RAML并提供语法建议,错误检测和实时模拟服务,并使用API Designer来测试你的API

MuleSoft系列(三)- 使用API设计器通过RAML定义API

在代码的编辑区域,我们先来写一个person的get接口,首先定义了get接口的header中必须从传入一个叫Required_Id的参数,然后可选参数包括字符串类型的name和枚举类型的type,在右侧API 控制台,可以看到实时显示你定义的接口内容,点击Get方法可以查看详细的内容

MuleSoft系列(三)- 使用API设计器通过RAML定义API MuleSoft系列(三)- 使用API设计器通过RAML定义API

然后继续添加get方法的响应体,这里我们学习如何引入左侧文档区域的内容,点击Files右侧的?,添加一个文件夹:DataType,然后在这个文件夹中创建一个文件:person-api.raml

MuleSoft系列(三)- 使用API设计器通过RAML定义APIMuleSoft系列(三)- 使用API设计器通过RAML定义APIMuleSoft系列(三)- 使用API设计器通过RAML定义API

定义的person-api如下,声明了id(可选),name,type,address,createdDate五个字段

#%RAML 1.0 DataType
displayName: person-api
description: Defines the fields in person Datatype

type: object
properties:
  id?: string
  name: string
  type: string
  address: string
  createdDate: datetime

在API中如何引用呢? 我们使用 !include 关键字

types:
  Person: !include DataType/person-api.raml

添加了Person类型之后,我们可以继续添加get方法的响应体,状态码为200时返回一个Person集合,但是在返回值上,我们希望能返回一些样例数据

responses:
      200:
        description: success
        body:
          application/json:
            type: Person[]
            examples:

所以这时候,我们再新建一个examples的文件夹,在里面添加一个带有测试样例的文件:person-example-api.raml, 里面的数据字段根据之前添加的Person对象添加

#%RAML 1.0 NamedExample

value:
  -
    id: 0001
    name: test name
    type: personal
    address: beijing
    createdDate: 2020-04-23T04:34:41.098Z
  -
    id: 0002
    name: ricardo
    type: business
    address: shanghai
    createdDate: 2020-04-22T04:34:41.098Z

回到编辑界面,我们再使用 !include 关键字,将测试样例添加到response中

examples:
              output: !include examples/person-example-api.raml

写完这一步后,我们可以打开右上角的模拟测试(Mocking Service), 选择GET方法,点击 Try It, 在填些必填的Required_Id之后,点击Send按钮,就能看到响应状态码200的返回值

MuleSoft系列(三)- 使用API设计器通过RAML定义API

MuleSoft系列(三)- 使用API设计器通过RAML定义API MuleSoft系列(三)- 使用API设计器通过RAML定义API

到这里为止,我们已经成功定义了一个get接口,下面附上完整的RAML描述

 1 #%RAML 1.0
 2 title: GetPerson
 3 
 4 types:
 5   Person: !include DataType/person-api.raml 
 6   
 7 /person:
 8   get:
 9     displayName: getPerson
10     description: get the person record
11     headers:
12       Required_Id:
13         type: string
14         required: true
15     queryParameters:
16       name:
17         displayName: person name
18         description: query by name
19         required: false
20         type: string
21       type:
22         displayName: person type
23         description: persons type
24         enum: [busines , personal]
25     responses:
26       200:
27         description: success
28         body:
29           application/json:
30             type: Person[]
31             examples:
32               output: !include examples/person-example-api.raml

当我们完成了接口的开发后,紧接着需要将接口发布出去,点击右上角的Publish, 选择Publish to Exchange,会弹窗出来填接口的版本号,格式要求:x.y.z,然后点Publish to Exchange,完成后,切换到Exchange,就能找到你刚刚发布的接口:GetPerson

MuleSoft系列(三)- 使用API设计器通过RAML定义APIMuleSoft系列(三)- 使用API设计器通过RAML定义API

点GetPerson接口进入详情界面,在这里你可以查看接口的详细信息,添加接口的描述信息,或者模拟接口测试,你可以将接口Share给你的同事,让他们可以查看这个接口,MuleSoft提供了一个评论系统,能查看这个接口的同事也可以对接口进行评论打分。当你需要发布新版本的接口时,你只要修改后重新publish即可

MuleSoft系列(三)- 使用API设计器通过RAML定义API

以上是对MuleSoft API Design整个操作周期的描述,了解了在Anypoint平台上应该如何应用API Design去设计一个API,测试接口的同时发布到Exchange上分享给别人使用

 

MuleSoft系列(三)- 使用API设计器通过RAML定义API

上一篇:18、vue-lazyload实现图片懒加载


下一篇:图片懒加载