API开发 CodeArts API支持生成接口请求代码和业务代码，缩短前后端开发时长，规范代码结构。 基于接口定义，CodeArts API支持自动生成各种语言和框架的请求代码和业务代码。在API设计模块，接口文档界面右侧，即可看到“生成代码”的入口。 生成接口请求代码 单击“生成代码”下拉框，选择“生成接口请求代码”，弹出“生成接口请求代码”对话框。 支持生成多种语言的接口请求代码，单击右上角，可一键复制并直接粘贴，支持编辑修改和代码格式化。 生成业务代码 单击“生成代码”下拉框，选择“生成业务代码”，弹出“生成业务代码”对话框。 根据需要选择语言、生成范围（包括“仅当前接口及关联模型”和“整个项目”），单击“生成”将生成的代码存储到本地，开发者可以将代码复制到本地的研发工具（如IntelliJ IDEA）。

Address相关 分类 规则 示例 示例结果 区域 @region @region() "西北" 省或直辖市、自治区、特别行政区 @province @province() "陕西省" 市 @city @city() "西安市" @city(prefix) @city(true) "陕西省 西安市" @city(false) "西安市" 县 @county @county() "蓝田县" @county(prefix) @county(true) "陕西省 西安市 蓝田县" @county(false) "蓝田县" 邮政编码 @zip @zip() "710500"

Name相关 分类 规则 示例 示例结果 英文名 @first @first() "Michelle" 英文姓 @last @last() "Williams" 英文姓名 @name @name() "Michelle Williams" @name(middle) @name(true) "Karen Lisa Harris" @name(false) "Karen Harris" 中文姓 @cfirst @cfirst() "张" 中文名 @clast() @clast() "三" 中文姓名 @cname @cname() "张三"

Helper 分类 规则 示例 示例结果 全大写 @upper(str) @upper("hello") "HELLO" 全小写 @lower(str) @lower("HELLO") "hello" 多选一 @pick(arr) @pick(["hello", "test", "test3"]) "hello" @pick([1, 5, 10, 60, 80]) 10 @pick([1,"hello","中国",true,80]) true

Web 相关 规则 示例 示例结果 @url @url() "http://ihum.md/xmicdyn" @url(protocol) @url("http") "http://ckpvjgyc.eg/jzatazzvm" @url(protocol,host) @url("http","test.com") "http://test.com/pmuway" @protocol @protocol() "ftp" @domain @domain() "ljmhm.gu" @domain(tld) @domain("com") "dtcboprfg.com" @tld @tld() "com" @email @email() "e.fsysqt@vjz.edu" @email @email("test.com") "e.fsysqt@test.com" @ip @ip() "xxx.xxx.xxx.xxx"

基础类型 分类 规则 示例 示例结果 布尔值 @boolean @boolean() false，true @boolean(min,max,current) @boolean(1,9,true) false，true 自然数 @natural @natural() 1350447356 @natural(min) @natural(10000) 819989031 @natural(min,max) @natural(60,100) 63 整数 @integer @integer 1128800169 @integer(min) @integer(10000) 29427959 @integer(min,max) @integer(60,100) 94 浮点数 @float @float() 13425418.3 @float(min) @float(0) 1800545158.8 @float(min,max) @float(60,100) 98.63203 @float(min,max,dmin) @float(60,100,3) 69.882191 @float(min,max,dmin,dmax) @float(60,100,3,5) 80.14955 单字符 @character @character() "7" @character(pool) @character("lower") "x" @character("upper") "R" @character("number") "6" @character("symbol") "#" @character("aeiou") "i" 字符串 @string @string() "%#Vwj" @string(length) @string(5) "^16)1" @string(pool,length) @string("lower",5) "zrcmq" @string("upper",5) "PFTFP" @string("number",5) "96480" @string("symbol",5) "#&!!(" @string("aeiou",5) "uoauu" @string(min,max) @string(7,10) "0B(6!)5[)" @string(pool,min,max) @string("lower",1,3) "zz" @string("upper",1,3) "OZJ" @string("number",1,3) "61" @string("symbol",1,3) "@%" @string("aeiou",1,3) "au" 范围 @range(stop) @range(10) [0,1,2,3,4,5,6,7,8,9] @range(start,stop) @range(3,7) [3,4,5,6] @range(start,stop,step) @range(1,10,3) [1,4,7]

日期/时间 分类 规则 示例 示例结果 日期 @date @date() "2015-05-09" @date(format) @date("yyyy-MM-dd") "2012-11-08" @date("yy-MM-dd") "10-06-12" @date("yyyy yy y MM M dd d") "1971 71 71 05 5 02 2" 时间 @datetime @datetime() "1996-15-11 01:18:47" @datetime(format) @datetime("yyyy-MM-dd A HH:mm:ss") "1978-01-10 AM 03:59:54" @datetime("yy-MM-dd a HH:mm:ss") "98-09-03 下午 19:32:44" 当前时间 @now @now() "2022-11-30 12:46:12" @now(unit) @now("year") "2022-01-01 00:00:00" @now("month") "2022-08-01 00:00:00" @now("week") "2022-08-09 00:00:00" @now("day") "2022-08-11 00:00:00" @now("hour") "2022-08-11 15:00:00" @now("minute") "2022-08-11 15:24:00" @now("second") "2022-08-11 15:24:02" @now(format) @now("yyyy-MM-dd HH:mm:ss SS") "2022-08-11 15:24:02 761" @now(unit,format) @now("day", "yyyy-MM-dd HH:mm:ss SS") "2022-08-11 00:00:00 000" 时间戳 @timestamp(format) @timestamp("s") "1662605353" @timestamp("ms") "1662605408838"

授权 IAM 账号 如果用户需要对所拥有的CodeArts API服务 进行精细的权限管理，可以使用 统一身份认证 服务（Identity and Access Management，简称IAM），通过IAM，可以： 根据企业的业务组织，在华为云账号中，给不同职能部门的员工创建IAM用户，让员工拥有唯一安全凭证使用CodeArts API资源。 根据企业用户的职能，设置不同的访问权限，实现权限隔离。 CodeArts API支持的系统权限如下： DevCloud Console ReadOnlyAccess：软件开发生产线控制台只读权限，授权后可正常使用CodeArts API产品，但不可创建项目。 DevCloud Console FullAccess：软件开发生产线控制台管理员权限，拥有该权限的用户可以购买CodeArts。 ProjectMan ConfigOperations：设置新建项目权限。

授权企业联邦账号 提供企业账户授权的启用、停用等操作。通过增加企业账户授权，您可以开放本企业账户的资源的使用权限给其他企业账户下用户。 华为云目前支持以下两种身份提供商类型： IAM用户SSO：身份提供商中的用户登录华为云后，系统将自动匹配外部身份ID绑定的对应IAM子用户，从而拥有该子用户所在用户组的权限。此类型账号与普通的IAM账号授权相同。 虚拟用户SSO：身份提供商中的用户登录华为云后，系统为其自动创建虚拟用户信息，并按照身份转换规则授权。 两种身份提供商的适用场景及配置方法可参照身份供应商概述。

邀请其他企业用户 企业A的账号中创建项目后，可以向该项目中添加企业B的账号中的IAM用户。 前提条件请参照邀请其他企业用户为项目成员。 单击“添加成员”旁的下拉框，选择“邀请其他企业用户”。 弹出“邀请其他企业用户”对话框，在“企业用户”下拉列表框中选择被邀请用户所属的账号，选择邀请方式并输入对应ID，单击“确定”。 用户ID：被邀请用户的ID，通过“我的凭证 ”获取“IAM用户ID”。获取方式请参考API凭证。 委托ID：被邀请账号中已创建的委托ID，通过IAM服务中的“委托”页面获取。 单击“确定”，可以将其他企业用户添加到项目中。

创建项目 拥有创建项目权限的用户可以在CodeArts API的控制台创建新的项目。 登录CodeArts API控制台，单击“创建项目”，弹出“创建项目”窗口。 填写项目基本信息。 表1 新建项目参数说明 字段名称 是否必填 备注说明 项目名称 是 项目名称，限制128个字符。 项目描述 否 项目描述，限制1024个字符。 单击“确定”，完成项目创建。 CodeArts API还支持查看和使用在软件开发生产线CodeArts中创建的IPD项目。

设计API 接口文档应针对以下要素进行设计： 接口基本信息 接口路径 请求方式 接口请求参数 接口返回响应 安全方案 接口基本信息 填写接口的基本信息，包括： operationId ：同OpenAPI（Swagger）规范里的operationId。 用于标识此接口的唯一字符串，在相同根目录下必须是唯一的，只允许输入英文和数字。 摘要：接口的摘要信息。 状态：API生命周期的状态，包括设计中、联调中、测试中、测试完、已发布、将废弃、已废弃。 所属目录：接口在项目中所属的目录。 所属Tags：接口所属的Tags，可以直接选择所属目录信息当作所属Tags，也可以在所属Tags框中手动输入Tag名再回车来生成所属Tags。 描述：可添加接口的相关描述，包括接口功能、使用注意事项、使用场景定义等详细描述信息，接口描述支持通用Markdown语言编辑。 接口路径 接口的URL，客户端可以通过接口路径向服务端发起请求。以“/”开头，如：“/car”、“/car/{owner}”。 接口路径一般不包含 域名 和http、https协议名，如需加上域名进行调试，在调试功能页面有相应处理。 大括号“{}”中间的字符串表示Path参数。 不支持通过接口路径来添加Query参数，如：“/car?owner=zhangsan”。 支持创建100个项目中根目录。 请求方式 定义接口的请求方式，制定了客户端对服务端资源操作的方法，在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体数据结构提取为数据模型，根据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 安全方案引入需要在公共模型中建立安全模型，详见•安全模型。

手动导入 通过主页面的“更多功能”选项或单击左上角搜索框旁边的，可以展示当前支持的导入选项，可根据需要选择。 导入文件 选择响应格式的文件并上传，然后选择文件中系统识别出来的接口和数据模型导入。 Postman支持Collections和Environment数据集ZIP包的全量导入，也支持单个Collection文件导入。 Postman支持接口和接口用例的前置脚本及后置脚本导入。 导入URL 选择“导入Swagger URL”，输入URL，即可完成文档导入。 通过Swagger URL导入时，需要填写json数据文件的URL，而非Swagger UI的URL。

创建Markdown文件 新建Markdown，可通过以下三种方式完成。 方法一：单击目录树搜索框右侧的，在弹出的下拉框中，选择“新建Markdown”。 方法二：在目录树中选择一个目录，单击右侧图标，在弹出的下拉框中，选择“新建Markdown”。 进入“新建标签页”，在该标签页可以编辑Markdown文件，主要包括：目录、名称、正文。 目录：在上一步中，如果通过方法一和方法二新建Markdown，目录初始内容为空，可以手动选择；如果通过方法三新建Markdown，目录会自动生成为选中的目录，也可以手动修改。 名称：可根据业务需要自定义命名，不能为空。命名规则：只支持中文、英文、下划线、数字和“.”，且以中英文开头，长度为3-64个字符。 正文：可手动输入文字，也可使用组件插入特定的内容，如：表格、超链接、图片；正文样式也可以使用组件进行调整；正文编辑支持全屏模式；在左侧编辑正文时，右侧会同步展示编辑内容，便于查看、修改样式等。 编辑完成后，单击右上角“保存”，左侧目录树同步刷新，界面会自动跳转到文档页面，展示名称、正文，上方标签页的名称也会更新为Markdown文件名称。 移动Markdown（可选）。 单击并拖拽Markdown到目标目录后释放即可，移动成功后，目录树会自动刷新，Markdown文件的目录也会同步改变。

测试用例导入 CodeArts API提供不同版本测试用例的导入功能。 在“版本管理”页面，单击目标版本操作列的，选择“导入”。 弹出“从版本导入测试用例”对话框。 填写导入信息，单击“确定”，完成测试用例的导入。 参数名称 说明 覆盖规则 勾选后，会覆盖编号重复用例和脚本，且无法回退。 版本选择 原版本：需要导入的测试用例版本。 目标版本：被导入测试用例的版本，不可更改。 用例选择 需要导入的测试用例列表。