YApi 官网说明文档-接口操作

简介: 为方便和前端, 节省沟通成本, 编写接口文档非常有比较使用过swagger, 觉得入侵性太大. POST又感觉和项目结合的不太紧密. 所以一直在寻找新的接口阅读/生成/测试工具. 下面介绍一下YApi.

为方便和前端, 节省沟通成本, 编写接口文档非常有比较


使用过swagger, 觉得入侵性太大. POST又感觉和项目结合的不太紧密. 所以一直在寻找


新的接口阅读/生成/测试工具. 下面介绍一下YApi.

如何创建接口?



把大象装进冰箱分几步?三步:把冰箱门打开,把大象装进去,关门,搞定~

新建接口分几步?也是三步:





搞定~


接口设置



进入项目页,可以看到项目下的所有接口,需要注意的是,YApi有 接口集合测试集合 两个概念。


  • 接口集合 将接口进行分类,使接口结构更清晰,一个接口只能属于一个集合,且不允许与其他接口重名。


  • 测试集合 为了方便我们测试接口,测试集合 将若干接口组合在一起,在这里一个接口可以属于不同集合。


接口配置


新建接口 后,点击新添加的接口,右侧可以看到接口的预览信息,点击右侧的 编辑 Tab项进入编辑面板。


在该面板中你可以看到接口的基本信息(接口名称、分类、路径),除此以外,你还可以完善以下接口信息:


基本设置


  • 接口路径:可以更改 HTTP 请求方式,并且支持 restful 动态路由,例如 /api/{id}/{name}, id和name是动态参数


  • 选择分类:可以更改接口所在分类


  • 状态:用于标识接口是否开发完成。


  • Tag:用于标识接口tag信息(v1.3.23+),在接口list页可以根据tag过滤接口


image.png


image


请求参数设置


  • Query参数: 接口 url 的查询字符串,点击『添加Query参数』按钮来添加参数,可以通过拖动来交换参数位置


  • 请求Body:http 请求 body 部分,如果http请求方式是 post, put 等请求方式时会有 req_body 部分。req_body_type 形式有4种,分别是 form, json, file 和 raw 。


  • Headers: http 请求头字段,在 req_body 形式是 form 格式下会在 header 中自动生成 'Content-Type application/x-www-form-urlencoded',其他3种格式也会自动生成不同 header


image.png


image


返回数据设置


  • 返回数据分为 json & raw 两种形式。基于 mockjs (具体使用方法详见Mock 介绍)和 json5,使用注释方式写参数说明。 为了方便数据编写可以按F9来使用全局编辑


  • 选择json-schema 则进入了 json 结构可视化编辑器形式, 数据以 json schema 格式解析 快速入门 Json Schema


image.png


image


备注 & 其他


  • 接口描述: 用简短的文字描述接口的作用。


  • 邮件通知:开启后将此次接口的改动以邮件的形式发送至项目组所有成员和关注该项目的成员(邮件默认情况下自动开启)


  • 开放接口:默认为关闭状态,用户可以在 数据导出 时选择只导出公开接口


接口运行



接口运行功能,是用来测试真实接口的,类似『Postman』的功能。


点击运行 tab ,可进入到接口测试页面,首先安装『chrome crossRequest』扩展,才可正常使用此功能。


点击保存按钮可把当前接口保存到测试集,方便下次调试。


安装完插件记得刷新页面


image.png


image


接口返回数据验证


版本 v1.3.22 新增返回数据验证功能, 如果接口的返回数据格式为json schema 在接口运行时会对接口返回数据和定义数据格式进行校验


image.png


Mock介绍



YApi的 Mock 功能可以根据用户的输入接口信息如协议、URL、接口名、请求头、请求参数、返回数据(返回数据)生成 Mock 接口,这些接口会自动生成模拟数据,创建者可以自由构造需要的数据。


mock地址解析YApi平台网址 + mock + 您的项目id + 接口实际请求path

假设你 YApi 的部署地址为:http://yapi.xxx.com 然后用这个地址作为示例

mockd 地址: http://yapi.xxx.com/mock/29/api/hackathon/login


注:项目 id 可以在项目设置里查看到


定义 mock 数据示例


项目 -> 接口编辑 -> 返回数据设置


返回数据设置有两种方式,最新版本默认是基于 json+注释 的方式,另外一种是基于 json-schema 定义数据结构,请根据实际情况灵活选择使用。


方式1. mockjs


image.png


image


原理


基于 mockjs,跟 Mockjs 区别是 yapi 基于 json + 注释 定义 mock 数据,无法使用 mockjs 原有的函数功能。


  1. 正则表达式需要基于 rule 书写,示例如下:


{
  "name|regexp": "[a-z0-9_]+?",
  "type|regexp": "json|text|xml"
}


  1. 支持替换请求的 query, body 参数


{
  "name": "${query.name}", //请求的url是/path?name=xiaoming, 返回的name字段是xiaoming
  "type": "${body.type}",   //请求的requestBody type=1,返回的type字段是1
}


  1. 示例

/**
 * 这是一个接口返回数据示例
 */
{
    "errcode": 0,
    "errmsg": "@word",
    "data": {
        "id": "@id", //@id 随机生成 id
        "name": "@name" //@name 随机生成用户名
    }
}


详细使用文档请查看:Mockjs 官网


方式2. json-schema



image.png


image


开启 json-schema 功能后,根据 json-schema 定义的数据结构,生成随机数据。


如何生成随机的邮箱或 ip(该方法在v1.3.22之后不再适用)?


image.png


image


点击高级设置,选择 format 选项,比如选择 email 则该字段生成随机邮箱字符串。


集成 mockjs


基本书写方式为 mock 的数据占位符@xxx, 具体字段详见Mockjs 官网


image.png


image


image.png


image


如果不是以@字符开头的话或者匹配不到Mockjs中的占位符就会直接生成输入的值


如何使用 Mock



1 在 js 代码直接请求yapi提供的 mock 地址(不用担心跨域问题)


在代码直接请求 yapi 提供的 mock 地址,以 jQuery 为例:


let prefix = 'http://yapi.xxx.com/mock/2817'
$.post(prefix+'/baseapi/path', {username: 'xxx'}, function(res){
    console.log(res) //返回上图预览部分的数据
})


2 基于本地服务器反向代理


优点:不用修改项目代码


2.1 基于 nginx 反向代理

location /baseapi
{
proxy_pass   http://yapi.xxx.com/mock/2817/baseapi; #baseapi后面没有"/"
}


2.1 基于 Charles 代理


点击 Charles 工具栏下的 tools >> Rewrite Settings 填写如下信息:


image.png

mock请求严格模式



版本 v1.3.22 新增 mock 接口请求字段参数验证功能,具体使用方法如下:


  1. 打开 项目 -> 设置 开启 mock 严格模式


  1. 针对 query, form 中设置的必须字段会进行必填校验


image.png


image


  1. 针对 req_body_type 是json schema 格式的数据进行校验



image.pngimage.pngimage.pngimage.png

image.png


来源


文章全文完全来自 YApi-教程.


https://hellosean1025.github.io/yapi/documents/index.html


目录
相关文章
|
NoSQL Cloud Native 数据可视化
云原生之使用Docker部署YApi接口管理服务平台
云原生之使用Docker部署YApi接口管理服务平台
599 0
云原生之使用Docker部署YApi接口管理服务平台
|
6月前
|
数据可视化 JavaScript NoSQL
搭建接口平台YApi详解(含搭建node环境)
搭建接口平台YApi详解(含搭建node环境)
191 0
|
Web App开发 JSON 安全
【漏洞复现】Yapi接口管理平台远程代码执行漏洞
Yapi接口管理平台远程代码执行漏洞,攻击者可通过特定Payload对目标实施恶意攻击,获取敏感信息,操控服务器指令。
613 1
|
前端开发 数据可视化 机器人
基于YAPI的接口工作流
基于YAPI的接口工作流
474 0
基于YAPI的接口工作流
|
存储 NoSQL JavaScript
Linux下快速搭建YApi接口管理平台
目录 一、序言 二、安装Node 1、安装nvm 2、使用兼容的Node版本 二、安装MongoDB 1、下载MongoDB 2、配置MongoDB 三、安装YApi 四、安装PM2管理Node服务 五、登录YApi后台
Linux下快速搭建YApi接口管理平台
|
数据可视化 数据管理 测试技术
02 提效工具之yapi接口生成
02 提效工具之yapi接口生成
|
XML JSON 前端开发
开源的YAPI外还有哪些免费的接口工具?
API 管理这个话题近些年听到的频次越来越多,这本质上是个 web 领域的发展有关,也和开发协作方式有关--前后端分离代替了全栈工程师 hold all 的局面,强调的更多的是 API 复用、分工和协作细化。 API 管理的重要性不言而喻,每家公司随着业务的发展,多多少少都会涉及到;从开源社区的产品到国内各类商业化产品,可以看到大家对于 API 管理是越来越重视的。
|
Kubernetes 数据可视化 测试技术
可视化接口管理平台 YApi,让你轻松搞定 API 的管理问题
高效、易用、功能强大的可视化接口管理平台 YApi,让我们能轻松帮助我们搞定 API 的管理问题。
746 1
|
JSON 前端开发 API
接口管理工具YApi怎么用?颜值高、易管理、超好用
接口管理工具YApi怎么用?颜值高、易管理、超好用
|
JSON 前端开发 API
接口管理工具YApi怎么用?颜值高、易管理、超好用
众多接口管理工具如雨后春笋搬冒出。让人欣慰的是,有许多优秀作品来自国内,包含YApi和rap。 看着中文的官网,熟悉的汉语,不禁让人暗爽。当然这也就带来另一个弊端,因为使用基数少,所以参考资料少。我们想学习使用方法,只能依赖官方文档,也算是福祸相倚了。 本文将带您走进Yapi的世界,让您体验一回小清新的接口管理工具。 根据统计,市面上互联网项目超过10亿,保守统计涉及的API数量有100亿。