更新时间:2022-03-18 GMT+08:00
分享

创建API设计

ROMA API提供了可视化的API在线设计能力,及接口规范性检查,帮助用户快速设计标准的RESTful API。在开始设计API前,您需要创建一个设计文件。

创建API文件

  1. 登录ROMA API控制台。
  2. 在控制台单击,选择区域,在“ROMA API”下选择待操作的应用。
  1. 在左侧导航栏单击“API设计”。
  2. 单击“创建API文件”。
  3. 在弹窗中修改“名称”,或默认系统自动生成的名称;根据下表说明,选择模板。

    表1 API文件模板

    模板类型

    类型说明

    SimpleAPI

    提供简单GET请求样例。

    DescriptionWithGFM

    提供如何在API的描述信息中使用markdown语法,使描述信息更直观。

    SimpleBookManagementAPI

    提供资源管理类的简单API样例。

    FileOperation

    提供如何定义文件操作类API的简单样例。

    Petstore

    提供多种复杂API的定义样例。

  4. 单击“确定”,跳转到API设计文件的“编辑器”页面。

    • 页面左侧为API列表,可选择API或数据模型查看。
    • 页面中间为API的编辑窗口,编辑API时应遵循Swagger 2.0规范定义。
    • 页面右侧为API的可视化视图窗口。

    在编辑API设计文件时,单个API最多支持写入1024000个字符(包括空格),超过此限制将无法保存设计文件。

  5. 完成编辑后,单击右上角的“保存”。

    您还可以执行以下操作。

  6. (可选)配置SLA。单击

    • 需要配置SLA的API所在行,单击“配置SLA”。
    • 勾选需要配置SLA的API,单击“批量配置SLA”。

  7. (可选)Mock调测。

    开启“Mock”会自动生成Mock服务地址,您可以在可视化窗口对接口地址进行调测。

  8. (可选)规范性检查。

    在规范性检查之前,您需提前启用规则集创建规则集。在编辑窗口上方单击“规范性检查”,检查结果在可视化视图窗口查看,您可以根据修改建议修改规范性问题。
    图1 规范性检查结果

  9. (可选)导入到API服务。

    1. 单击“导入到API服务”,系统根据默认API导入规则检测API文件。
    2. 如需修复问题,单击“修复问题”根据修改建议修改问题。
      图2 API导入规则检查结果
    3. 如忽略问题,可单击“继续导入”。

  10. (可选)可视化设计API文件。

    单击“表单”页签,您可以创建多个API文件或对API文件进行分类,以及可视化编辑API接口等。
    • 在“API列表”区域,单击,创建API。
    • 在“API列表”区域,单击,对API进行分类管理。
    • 单击“文件基本信息”页签,查看设计文件基本信息。
    • 单击“编辑”,对API进行编辑或修改。

导入Swagger文件

  1. 登录ROMA API控制台。
  2. 在控制台单击,选择区域,在“ROMA API”下选择待操作的应用。
  3. 在左侧导航栏单击“API设计”。
  4. 单击“导入Swagger文件”。
  5. 在弹窗中选择本地路径下的API设计文件,单击“打开”导入文件。

    导入的YAML或JSON格式文件内容应满足Swagger 2.0规范定义。

  6. 页面自动跳转到“编辑器”页面,如需编辑导入后的设计文件,请参考6~12

批量导入Swagger文件

  1. 登录ROMA API控制台。
  2. 在控制台单击,选择区域,在“ROMA API”下选择待操作的应用。
  3. 在左侧导航栏单击“API设计”。
  4. 单击“批量导入Swagger文件”。
  5. 在弹窗中选择本地路径下的API设计文件包,单击“打开”导入文件包。

    • 导入的YAML或JSON格式文件内容应满足Swagger 2.0规范定义。
    • 导入的zip压缩包大小不能超过1MB,单个YAML或JSON格式文件中内容不能超过1024000个字符(包括空格),否则将无法导入设计文件。

  6. 页面自动跳转到设计文件列表页面,如需编辑导入后的设计文件,请参考6~12

创建API设计

  1. 登录ROMA API控制台。
  2. 在控制台单击,选择区域,在“ROMA API”下选择待操作的应用。
  3. 在左侧导航栏单击“API设计”。
  4. (可选)按文件夹将API设计文件分类,需要创建文件夹。

    单击页面右上角的“创建API设计 > 创建文件夹”,创建一个文件夹。然后单击文件夹名称,进入文件夹。

  5. 单击页面右上角的“创建API设计”。

相关文档