更新时间:2024-06-18 GMT+08:00
分享

API设计

API(应用程序编程接口)设计是API全生命周期的第一步,其含义是通过规定接口的路径、所属目录、Tag、请求参数、请求体等来定义接口,从而帮助开发人员在沟通中对某一接口有着同样、确定的定义。

新建API

进入CodeArts API目标项目后,单击主页面的“新建API接口”选项,创建http类型接口。

也可以单击左侧搜索框旁边的,选择下拉选项中的“新建API接口”,创建http类型接口。

设计API

接口文档应针对以下要素进行设计:

  • 接口基本信息
  • 接口路径
  • 请求方式
  • 接口请求参数
  • 接口返回响应
  • 安全方案

接口基本信息

填写接口的基本信息,包括:

  • 名称:接口名称。
  • 摘要:接口的摘要信息。
  • 状态:API生命周期的状态,包括设计中、联调中、测试中、测试完、已发布、将废弃、已废弃。
  • 所属目录:接口在项目中所属的目录。
  • 所属Tags:接口所属的Tags,可以直接选择所属目录信息当作所属Tags,也可以在所属Tags框中手动输入Tag名再回车来生成所属Tags。
  • 描述:可添加接口的相关描述,包括接口功能、使用注意事项、使用场景定义等详细描述信息,接口描述支持通用Markdown语言编辑。

接口路径

接口的URL,客户端可以通过接口路径向服务端发起请求。以“/”开头,如:“/car”、“/car/{owner}”。

  • 接口路径一般不包含域名和http、https协议名,如需加上域名进行调试,在调试功能页面有相应处理。
  • 大括号“{}”中间的字符串表示Path参数。
  • 不支持通过接口路径来添加Query参数,如:“/car?owner=zhangsan”。

请求方式

定义接口的请求方式,制定了客户端对服务端资源操作的方法,在API设计过程中,需要根据业务和操作类型选择合适的请求方式。

  • GET(获取):用于获取指定资源,使用查询参数传递参数,适用于读取资源和查询数据。
  • POST(提交):用于提交数据。POST请求可以传递请求体参数,适用创建新资源、提交表单数据或执行某些操作等场景。
  • PUT(更新):用于更新或替换服务端的指定资源。
  • DELETE(删除):用于删除服务端的指定资源。
  • OPTIONS(选项):用于获取服务器支持的http方法和资源的相关信息。可用于客户端与服务端之间的握手过程,了解服务器所支持的方法和功能。
  • HEAD(请求头):与GET类似,但只返回响应头部,不返回实体内容,用于获取资源的元信息,如:文件大小、修改日期等。
  • PATCH(补丁):用于对资源进行局部更新。PATCH请求类似于PUT请求,但是只更新资源的一部分。
  • TRACE(跟踪):用于简历与代理服务器的隧道连接,通常用于进行安全的SSL/TLS加密通信。

接口请求参数

  • Params、Path、Header、Cookies
    • Query参数:接口请求中的一种参数传递方式,它通常用于传递一些可选的参数,比如过滤条件、排序方式、分页参数等。在URL中表现为末尾“?”后的字符串(如:“/car?owner=zhangsan”,那么“owner=zhangsan”即Query参数,其中“owner”为参数的key,“zhangsan”为参数的value)。
    • Path参数:也称为“路径参数”,是API请求中的一种参数传递方式。在URL中表现为大括号“{}”括起来的字符串(如:“/car/{owner}”,那么“{owner}”表示key为“owner”的Path参数)。
    • Header参数:请求头中的参数。
    • Cookies:类型为“小型文本文件”,是某些网站为了辨别用户身份,进行Session跟踪而储存在用户本地终端上的数据(通常经过加密),由用户客户端计算机暂时或永久保存的信息。
    • 前置脚本:CodeArts API支持接口前置脚本操作,详见脚本能力
    • 后置脚本:CodeArts API支持接口后置脚本操作,详见脚本能力

  • 请求体
    在发起http请求时,需要带上一些参数以便服务器处理,通过http请求体传递的参数被称为Body参数。Body参数包含在请求的主体部分中,通常是一些表单数据、JSON数据或者二进制数据。在发送请求时,会根据Body参数类型,自动在请求Header中添加对应Content-Type参数。若手工设置Content-Type的类型,则必须与Body的参数类型匹配,否则系统会自动忽略掉手动设置的Content-Type值。
    • none:无body参数。
    • application/json:json格式数据。Content-Type为 “application/json”。
    • application/xml:xml类型数据,用于标识文件和图像等没提类型,也可以标识结构化数据。Content-Type为 “application/xml”。
    • multipart/form-data:表单数据。Content-Type为 “multipart/form-data”。
    • application/x-www-form-urlencoded:将表单数据编码后传输到服务器。数据被编码为一系列键值对,每个键值对之间以&连接,并且键与值之间以=分隔。Content-Type为“application/x-www-form-urlencoded” 。

    此外,还支持根据Body体数据结构自动生成示例,以及单击“智能导入”,根据输入的Json自动生成数据结构功能。

接口返回响应

返回响应的定义包含:返回响应的状态码、响应内容的数据结构、响应示例和响应头。

  • 返回响应的状态码:通过加号来添加运行接口后可能的响应状态码,单击响应状态码可以对状态码进行修改。
  • 响应内容的数据结构:规定响应内容的格式,分为“application/json”、“application/xml”、“text/plain”三种,“application/json”和“application/xml”两种情况下可以对响应内容的结构进行进一步定义,如:响应内容为“application/json”,规定json内容里的参数类型等。
  • 响应示例:响应内容的示例。
  • 响应头:返回响应的Header。

返回响应也可以直接引用公共模型中已定义好的“公共响应”,并且支持自动生成响应示例。

安全方案

OpenAPI规范中,安全模型对应OpenAPI3.0的components.securitySchemes。大部分的Web服务都需要经过身份认证才能访问,security就是用于描述API的安全信息和访问授权协议等信息的对象,Open API支持的最常见授权方案如下:

  • API key
  • HTTP
  • Oauth2.0
  • OpenID Connect

安全方案引入需要在公共模型中建立安全模型,详见•安全模型

API文档

API设计完成后,单击“保存”,会自动跳转到API文档页面。如果单击左侧导航栏中的API,默认进入API文档页面。

API文档页面展示了定义好的API信息,包括API路径、请求参数、请求体、返回响应等信息,可通过右侧文档目录切换至对应模块进行查看。在文档展示页面,可以修改API状态。单击“运行”,可切换到调试页面进行API调试。

分享:

    相关文档

    相关产品