# API设计 API（应用程序编程接口）设计是API全生命周期的第一步，其含义是通过规定接口的路径、所属目录、Tag、请求参数、请求体等来定义接口，从而帮助开发人员在沟通中对某一接口有着同样、确定的定义。 #### 新建API 进入CodeArts API目标项目后，单击左侧搜索框旁边的，选择下拉选项中的"新建API接口"，创建http类型接口。 ![](https://support.huaweicloud.com/usermanual-apiarts/zh-cn_image_0000002515664015.png) #### 设计API 接口文档应针对以下要素进行设计： - 接口基本信息 - 接口路径 - 请求方式 - 接口请求参数 - 接口返回响应 - 安全方案 **接口基本信息** 填写接口的基本信息，包括： - operationId ：同OpenAPI（Swagger）规范里的operationId。 用于标识此接口的唯一字符串，在相同根目录下必须是唯一的，只允许输入英文和数字。 - 摘要：接口的摘要信息。 - 状态：API生命周期的状态，包括设计中、联调中、测试中、测试完、已发布、将废弃、已废弃。 - 所属目录：接口在项目中所属的目录。 - 所属Tags：接口所属的Tags，可以直接选择所属目录信息当作所属Tags，也可以在所属Tags框中手动输入Tag名再回车来生成所属Tags。 - 描述：可添加接口的相关描述，包括接口功能、使用注意事项、使用场景定义等详细描述信息，接口描述支持通用Markdown语言编辑。 ![](https://support.huaweicloud.com/usermanual-apiarts/zh-cn_image_0000002483384056.png) **接口路径** 接口的URL，客户端可以通过接口路径向服务端发起请求。以"/"开头，如："/car"、"/car/{owner}"。 ![](https://support.huaweicloud.com/usermanual-apiarts/zh-cn_image_0000002515664013.png) ![](https://support.huaweicloud.com/usermanual-apiarts/public_sys-resources/note_3.0-zh-cn.png) - 接口路径一般不包含域名和http、https协议名，如需加上域名进行调试，在调试功能页面有相应处理。 - 大括号"{}"中间的字符串表示Path参数。 - 不支持通过接口路径来添加Query参数，如："/car?owner=zhangsan"。 - 支持创建100个项目中根目录。 **请求方式** 定义接口的请求方式，制定了客户端对服务端资源操作的方法，在API设计过程中，需要根据业务和操作类型选择合适的请求方式。 - GET（获取）：用于获取指定资源，使用查询参数传递参数，适用于读取资源和查询数据。 - POST（提交）：用于提交数据。POST请求可以传递请求体参数，适用创建新资源、提交表单数据或执行某些操作等场景。 - PUT（更新）：用于更新或替换服务端的指定资源。 - DELETE（删除）：用于删除服务端的指定资源。 - OPTIONS（选项）：用于获取服务器支持的http方法和资源的相关信息。可用于客户端与服务端之间的握手过程，了解服务器所支持的方法和功能。 - HEAD（请求头）：与GET类似，但只返回响应头部，不返回实体内容，用于获取资源的元信息，如：文件大小、修改日期等。 - PATCH（补丁）：用于对资源进行局部更新。PATCH请求类似于PUT请求，但是只更新资源的一部分。 - TRACE（跟踪）：用于建立与代理服务器的隧道连接，通常用于进行安全的SSL/TLS加密通信。 ![](https://support.huaweicloud.com/usermanual-apiarts/zh-cn_image_0000002483544022.png) **接口请求参数** - 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支持接口前置脚本操作，详见[脚本能力](https://support.huaweicloud.com/usermanual-apiarts/apiarts_01_0026.html)。 - 后置脚本：CodeArts API支持接口后置脚本操作，详见[脚本能力](https://support.huaweicloud.com/usermanual-apiarts/apiarts_01_0026.html)。 ![](https://support.huaweicloud.com/usermanual-apiarts/zh-cn_image_0000002483384060.png) - 请求体 在发起http请求时，需要带上一些参数以便服务器处理，通过http请求体传递的参数被称为Body参数。Body参数包含在请求的主体部分中，通常是一些表单数据、JSON数据或者二进制数据。在发送请求时，会根据Body参数类型，自动在请求Header中添加对应Content-Type参数。若手工设置Content-Type的类型，则必须与Body的参数类型匹配，否则系统会自动忽略掉手动设置的Content-Type值。 - none：无body参数。 - raw：允许直接发送原始数据，如 JSON或纯文本。Content-Type为"application/json"或"application/text"。 - XML：xml类型数据，用于标识文件和图像等媒体类型，也可以标识结构化数据。Content-Type为 "application/xml"。 - form-data：表单数据。Content-Type为 "multipart/form-data"。 - x-www-form-urlencoded：将表单数据编码后传输到服务器。数据被编码为一系列键值对，每个键值对之间以\&连接，并且键与值之间以=分隔。Content-Type为"application/x-www-form-urlencoded" 。 ![](https://support.huaweicloud.com/usermanual-apiarts/zh-cn_image_0000002483384058.png) 此外，还支持将Body体数据结构提取为数据模型，根据Body体数据结构自动生成示例、以及单击"智能导入"，根据输入的Json自动生成数据结构功能。 **接口返回响应** 返回响应的定义包含：返回响应的状态码、响应内容的数据结构、响应示例和响应头。 - 返回响应的状态码：通过加号来添加运行接口后可能的响应状态码，单击响应状态码可以对状态码进行修改。 - 响应内容的数据结构：规定响应内容的格式，分为"application/json"、"application/xml"、"text/plain"三种，"application/json"和"application/xml"两种情况下可以对响应内容的结构进行进一步定义，如：响应内容为"application/json"，规定json内容里的参数类型等。另外还支持将响应体数据结构提取为数据模型。 - 响应示例：响应内容的示例。 - 响应头：返回响应的Header。 返回响应也可以直接引用公共模型中已定义好的"公共响应"，并且支持自动生成响应示例。 ![](https://support.huaweicloud.com/usermanual-apiarts/zh-cn_image_0000002515584009.png) **安全方案** OpenAPI规范中，安全模型对应OpenAPI3.0的components.securitySchemes。大部分的Web服务都需要经过身份认证才能访问，security就是用于描述API的安全信息和访问授权协议等信息的对象，Open API支持的最常见授权方案如下： - API key - HTTP - Oauth2.0 - OpenID Connect 安全方案引入需要在公共模型中建立安全模型，详见[•安全模型](https://support.huaweicloud.com/usermanual-apiarts/apiarts_01_0025.html#apiarts_01_0025__section5248496618)。 ![](https://support.huaweicloud.com/usermanual-apiarts/zh-cn_image_0000002483544020.png) #### API文档 API设计完成后，单击"保存"，会自动跳转到API文档页面。如果单击左侧导航栏中的API，默认进入API文档页面。 API文档页面展示了定义好的API信息，包括API路径、请求参数、请求体、返回响应等信息，可通过右侧文档目录切换至对应模块进行查看。在文档展示页面，可以修改API状态。单击"运行"，可切换到调试页面进行API调试。 ![](https://support.huaweicloud.com/usermanual-apiarts/zh-cn_image_0000002515584011.png)