API服务接口

API服务接口是在网关描述服务的重要组成部分,一般来说,对于所有不允许匿名访问的API,都需要在网关配置服务接口

注:即使是允许匿名访问的API,原则上也要求配置服务接口。

什么是服务接口

服务接口指的是一个API下的虚拟子路径,用于真正提供API某个具体功能的路径。

假设我们注册了一个API,路径如下:

https://developer.bingosoft.net:12000/demo

这个提供API提供了两个功能,查询用户和查询用户组:

查询用户:GET https://developer.bingosoft.net:12000/demo/user
查询用户组:GET https://developer.bingosoft.net:12000/demo/group

在这个示例中包含了两个服务接口:

GET /user
GET /group

从这里我们可以看到,一个服务接口至少包含了HTTP请求方法(operation)和虚拟路径(path),以便完整描述这个功能接口的调用方法。

实际上,一个完整的服务接口,包含了如下属性:

属性 示例 说明
路径(path) /user API路径下的子路径
操作(operation) GET/POST HTTP请求方法
参数(parameter) name=zhangs HTTP请求参数
响应(response) - HTTP请求响应

服务接口配置

服务接口的配置有两种方式:

swagger导入(推荐)

控制台配置服务接口支持使用标准的swagger文档导入生成。

API管理>我的API>选中一个API>服务接口>导入

这里支持输入json格式的swagger文档,或者一个能够获取到json格式swagger文档的http url地址。

输入后点击确定即可导入。

控制台配置

如果不使用swagger导入,可以直接通过控制台操作配置服务接口。

API管理>我的API>选中一个API>服务接口>添加接口

1. 添加服务接口(path)

这里各个属性说明如下:

属性 示例 说明
访问路径 /user path
名称 获取用户 用于显示这个服务接口的名称
父路径 - 这个path的父path,如/user/get的父路径是/user
选择分类 查询 将这个path分配到某个分类下
描述 查询所有用户的接口 对这个path的简要说明

2. 添加操作(operation)

这里需要填写操作的基本信息,各个属性说明如下:

基本信息

属性 示例 说明
显示名称 查询用户 用于显示的名称,一般要求有明确的业务含义
请求方法 GET HTTP方法
路径 /user 不可改变,指的是这个operation所属的path
描述 根据参数查询所有用户 对这个operation的简要描述
是否登录 是/否 客户端的访问令牌是否需要包含用户信息
权限 - 客户端调用这个operation需要申请的权限

API的权限定义请参考API权限定义

请求参数

属性 示例 说明
参数名 name http请求的参数名
参数位置 query 参数传递的方式,可选值的含义请参考swagger规范
参数类型 string 参数的类型,可选值的含义请参考swagger规范
描述 指定用户名 参数含义说明
必填/选填 - 选择这个参数是否必须传递

点击添加参数按钮可以添加多个参数。

请求响应

属性 示例 说明
状态码 200 http请求返回的状态码
数据类型 array 返回值类型,可选值的含义请参考swagger规范
引用类型 string 数据类型如果是对象类型(array/object)的情况下,需要指定具体的类型
描述 正常响应 描述当接口返回这个结果时代表的含义

点击+请求响应可以添加多个请求响应,并描述不同的请求响应代表的不同结果。

结果

无论采用swagger导入还是控制台配置,最终都需要定义完整的服务接口,如下:

定义完成后,客户端在服务目录中搜索到这个API时,就可以在服务接口文档中看到我们定义的接口和参数:

上一篇:下架API 下一篇:API服务文档