docAPI-使用说明

[wangzhenhui1991]

docApi使用说明

@(示例笔记本)[docApi, mock, swaggerapi]

---

[TOC]

概述

一个接口流程大致为 接口请求基本信息

1. 新建项目&编辑项目

1. 退出：指的是退出当前项目，退出后在列表中看不到该项目，其他成员依然可以看到
2. 复制：指的是复制项目的基本信息，方便快速创建。
3. 删除：指的是删除项目本身，删除后项目中的所有成员都看不到，只有管理员才有该权限，慎用

点击项目列表的右上角新增按钮，跳出项目新增窗口.

注意："接口基路径"属性为项目的英文名称，可在编码查询框中搜索，也定义一个文档的基础路径。

2. 编辑项目基础信息

点击接口基路径进入项目基础信息管理页面 右侧显示管理项目详细信息的侧边栏，有项目基本信息，项目成员，变更通知，变更历史，API文档信息，模块管理，接口管理和数据结构模块

3. 管理项目成员

1. 邀请成员：通过邮件邀请，邀请者注册登陆后点击邀请链接加入项目
2. 编辑成员：目前角色只有"管理员"和"访客"两种，其中只有"管理员"才有编辑权限,默认邀请的角色为"访客"
3. 移除成员：可移除人员成员，必须保证至少要有一名角色为"管理员"成员

注意:成员角色的改变在下次登陆后生效

4. 变更通知 && 变更历史

可以通过发送邮件的形式，向项目成员发送变更通知。

项目变更历史也会显示在变更历史列表中。 点击变更列表右上角新增日志，手动添加变更日志。

5. 编辑API文档

访问主机，可配置为外网，局域网或本机ip，因为测试是基于本地的ajax请求， 所以只要API所在服务器处理好跨域请求都支持网站在线测试API。

• 文档标题：
• 访问主机：(必填)定义API文档中接口访问的host,例如:doc.tuhu.cn，localhost:8080
• 接口基路径：(必填)定义API文档中接口访问的根路径,如/v2，则API中定义的所有路径都是在/v2之后.
• 文档版本：设置当前API文档的
• 文档说明：
• 是否发布：默认：是

6. 模块管理

主要用于对API接口进行分类，方便管理，可以不设置，默认全部在"default"组下面

API文档预览展示的模块顺序为升序，如需按要求排序可在模块名称前加序号指定

• 模块编辑：
• 模块删除：

7. 编辑数据结构

数据结构主要用于固定格式的服务器响应结构，适用于多个接口可能返回相同的数据结构，编辑保存后相关的引用都会变更。

使用情况：当请求参数为body时，使用数据结构中定义的object对象

基本数据类型：

• string：字符串类型，如"enter code here"
• boolean：布尔类型,如true|false
• int：短整型,如123
• long：长整型,如123456789
• float：浮点型
• double：浮点型
• decimal：精确到比较高的浮点型

复合数据类型：

• array：数组类型，可创建复合结构，可内部嵌套基础数据类型
• object：对象类型，可创建复合结构
• ref：引用类型，即引用定义好的object数据结构

示例

1. 定义Category

定义一个Category对象，包含一个id和name字段，类型分别为int和string

2.定义Pet

定义一个pet对象，其中字段category的类型为ref，指向我们上面定义的Category； 字段photoUrls类型为array

8. 接口管理

• 新增接口：点击接口列表右上角新增，可以添加新的接口。详见编辑接口基本信息
• 编辑接口：
• 删除接口：
• mock数据：
• 编辑接口详细信息: 点击接口的名称，可以编辑接口详细信息

提供模块分类查询接口

8.1 编辑接口基本信息

• 请求url：设置接口请求的路径,这个路径跟文档的基路径和主机定义了该接口的完整路径: 文档host+文档基路径+请求url
• 请求方式：设置接口请求的方式，目前只支持get，post，delete，put

  注意："请求url"和"请求方式"两者唯一确定一个接口，不能重复

  8.2 编辑接口请求参数

参数位置说明如下：

• query：http请求拼接，如getInfo?userId={userId}

  注意：请求url的定义方式，参数query的name为id，那么该接口的url无需额外定义

• path：http请求url，

  注意：请求url的定义方式,若参数path的name为userId，那么该接口的url应为getInfo/{userId}

• body：http请求body，

  注意：类型应为ref

• formData：表单参数，用于文件上传,

  注意：类型应为file

• cookie：定义http请求cookie

• header：定义http请求header

8.3 编辑接口响应信息

目前接口的响应信息实际应该在Mock数据操作中定义，在mock数据中会详细定义

注意：指定默认响应时，只需将响应"编码"设置为"default"即可

8.4 mock数据

当接口的所有定义部分结束，我们可以点击接口管理 中每个接口对应的mock数据按钮来自定义接口返回的内容

1.添加接口

首先我们添加一个接口，请求方式为get，请求url为/pet/{id}，

2.设置请求参数

参数名为id，参数位置为path，参数类型为int，点击保存。

3.点击mockData

这样我们算定义好了一个接口的请求格式，接下来需要定义这个接口的返回内容，我们点击get pet的mock数据

4.编辑mockBin(响应实体)

自动跳转到 mock响应数据的编辑界面

1. PATH：编辑path为/v/pet/112，意为我们定义了一个id为112的pet，我们可以通过GET /v2/pet/112路径来获取我们112的信息

2. Method：默认为get，和我们接口定义的请求方式相对应，不需要修改。

3. Status Code：设置响应编码，默认：200

4. Status Text：设置响应文本，默认：ok

5. Headers：设置响应头键值对

   • name：响应头key
   • value：响应头value

6. Cookies：设置响应Cookies键值对，设置同Headers

   注意：

7. Body：设置响应正文

8. mimeType：设置响应mimeType，默认为text/plian

点击Create Bin提交创建，我们就mock了一个响应实体(Bin).

5.查看mockBin信息

创建完成之后，我们可以跳转到mock数据的列表页面，我们可以在这个界面管理mock Bin。

当我们要创建的接口已经存在响应Bin的时候，也会自动跳转到列表页面

• paths 侧边栏：可以跳转到其他mock Bin的列表页面
• 查看Bin详情：点击Bin可以展开详情
• 查看Bin日志：点击日志按钮，可以查看Bin的访问记录

  6.修改mockBin信息

  点击列表的编辑按钮可以再次修改Bin的信息

  除了path 和 Method信息，其他的都可以修改

9. 预览发布

1.预览

返回到TuhuApi的预览功能，将生成对应API文档。

我们定义的所有接口信息都可以在这个页面中看到。

2. Try it out!

根据我们之前定义的/v2/pet/112，我们编辑id的value为112,点击Try it out!,当我们发送的请求符合我们接口定义的请求格式之后，就可以得到对应的Bin。