ESB接口规范化操作说明

接口导入

• ESB接口的接入方式，本文档就不详细介绍了，最推荐的接入方式是从OpenAPI文档中导入，一般项目，比如Java项目中集成了Swagger，就能拿到对应的OpenAPI文档，可以在注册API时，一键导入。
• 一般通过OpenAPI导入的接口，仅需要进行很小的修改即可发布使用
  • 修改接口授权方式，目前通用的认证方式是appkey

接口设置

• 如果是通过OpenAPI导入的接口，如果你的接口是按照OpenAPI标准化编写的，比如Java项目，接口的参数、接口说明都加了对应的Swagger注解，那在导入后，参数都能在将接口导入到ESB时，一起接进来，可参考下图，图中参数就是OpenAPI导入时，同时接入进来的。
• 点击接口左侧的+号，即可打开相关设置页面
• 主要有下面几个分栏
  • 输入参数
    • 对接口的输入参数进行增删编辑
    • 对输入的参数进行类型、位置、参数说明、是否必填等属性进行设置
    • 设置了必填参数，在ESB调用时，就会对请求接口进行校验，过滤掉无效请求
  • 输出参数
    • 对接口的输出参数进行增删编辑
    • 可设置参数类型、参数说明、是否必定包含等属性
  • Header
    • 对接口的header增删编辑
    • 可设置header 名称、值、传递方式等
  • 错误码
    • 对接口返回的编码进行增删编辑
    • 如果接口会返回多个错误码，可在这里进行设置，让调用者在调用的时候可看到接口可能返回的所有错误码
  • 更多配置
    • 可以对接口的返回数据类型进行设置
    • 可以设置RequestBody的参数类型
      • 单个JSON
      • JSON数组
      • 任意字符串
    • 可以设置RequestBody的请求示例
    • 可以设置成功返回示例
    • 可以设置调用失败返回示例
    • 可以添加补充说明，比如接口的Swagger文档
    • 可以添加附件
    • 如果接口的参数是纯数组，目前ESB不能很好的支持这种形式的参数，推荐转换为JSON对象形式的参数
  • 控制规则
    • 可以查看接口绑定的相关规则，比如统一认证规则
  • 变更日志
    • 可以查看接口的变更记录
  • 调用日志
    • 可以查看接口的调用记录
    • 只能选择日志库，以及对应的时间，无法通过其他参数进行查询

接口管理

接口设置完成后，可以发布更新，发布完成即可在API管理中看到自己更新发布后的接口了

• 可以在左侧点击切换，切换到想要查看的接口对应的应用系统
• 选中后，点击搜索按钮即可看到该应用下的所有接口列表，如果还需要进一步过滤，可继续在框中输入过滤条件
• 选择想要查看的接口，即可看到对应的接口文档说明
  • 接口文档准备的越全面，这里能看到的就越详细，调用方调用时候就能很快的明白，该接口应该如果使用，参数有哪些，返回值是什么样的，在调用时候需要再麻烦接口提供方的地方就越少。
  • 还可以直接获取到分享链接，打开被分享的链接，不需要登录到ESB系统，也能看到对应文档。