# AECORE SP入驻手册

联系人 逯浩圻(luhaoqi@glodon.com ) 刘大泽(liudz@glodon.com)

名词解释

  • AECORE Architecture, Engineering & Construction Core 是建筑，工程，结构的简称，AECore代表了平台为建筑领域提供基础行业服务应用的理念
  • SP Service Provider 服务提供者
  • ISV Independent Software Vendors 这里指应用开发者

# SP信息注册

要想将您的服务所具备的通用业务能力共享出来，首先需要以SP的身份完成注册。

1）填写服务基本信息；

2）填写服务类型信息；

登录AECORE，导航栏选择并进入服务管理，填写服务基本信息。

说明

SP注册当前仅面向广联达公司内部员工开放，若要使用，请使用公司邮箱注册广联达账号登录AECORE

  • 登录

  • 选择服务管理

  • 点击：注册技术产品

  • 填写技术产品或服务基本信息

基本信息包括：

技术产品名称、英文标识（全局唯一，用于标识服务，请起有意义的名称）、技术产品简介、联系人邮箱与电话，选择服务类型（本节主要讲述API类型服务）

  • 填写API服务类型信息

字段说明：

AppKey：

1）如果已经有从用户中心获取的appkey，请输入appkey；

2）如果是第一次升级为服务，并且没有appkey，可以选择系统创建；

Resourceid：

服务资源标识，全局唯一，可=技术产品英文标识，用英文命名一个可读的信息，如GDoc、BIMFACE等。

如原来已经在用户中心拥有resourceid，请直接填写。

服务开通通知地址：

开发者通过AECORE开通服务后，如果需要AECORE通知，请填写回调通知地址。回调url定义：查看文档

服务开通限制类型：

1）应用级：以appkey级别开通，即服务开通只以appkey为维度；

2）用户级：只允许userid对应的一个appkey开通（目前BIMFACE为这类）。

点击提交完成服务基本及类型信息注册。此时服务已具备checktoken的能力，接下来讲述如何将接口注册到AECORE的统一网关上。

# API接口注册

API接口注册步骤：

1）环境注册；

2）API接口注册；

3）定义服务scope（选做，不定义scope即服务所有资源向订阅应用开放）；

以下具体说明每个步骤怎么做

1）环境注册——创建服务环境。完成API类型信息提交后，系统默认进入到API管理-环境管理配置页

字段说明：

**服务名称：**即技术服务的中文名称，如果是多个微服务，可创建多个服务环境；

如：短信邮件服务；授权-订单服务、授权-会员中心

**环境：**即API对应的服务环境，当前支持配置接口对应的：正式、测试、预发布环境；

**ResourceId：**填写不同环境对应的resourceid信息；

**Appkey：**填写不同环境resourceid对应的appkey信息

**AppKey来源：**选择手动填写appkey对应的用户中心的环境，注意：appkey与环境对应错误会导致验权失败。AECORE默认生成的appkey对应用户中心环境唯一，不可修改；

**服务端点：**服务访问的地址，如：https://xxxx.glodon.com，如果是微服务的形式请写到最后的请求地址，如：https://api.glodon.com/xxx

**context_path：**网关统一接口端点，即通过此端点就知道是哪个服务，建议=技术产品英文标识。

说明

关于技术产品的英文标识建议全局统一，即技术产品英文标识=resourceid=context_path（由于历史原因已经存在的服务，如果不符合，就按照实际情况填写，此处系统并未做强制限制）

2）API接口注册

  • 支持swagger导入：针对使用了swagger的java服务，可导出swagger.json，通过系统导入完成接口批量注册

  • 手动创建（根据页面引导填写）

批量导入swagger，请填写对应的服务名称（尤其是在多微服务的情况下），以便于后期根据服务名称筛选API

新建API，根据页面引导操作：

3）定义服务scope

服务scope为服务权限范围，由服务负责人在scope管理页面定义，在API列表页面绑定scope与API关系（scope与API是n:n关系）

将API于scope关系绑定，可针对单个接口逐一绑定scope，也可以多选接口批量绑定

# 发布文档

# 文档规范

API类服务文档规范可参考：API类服务doc模板

如果本服务即提供API接口又提供控制台页面操作，可根据SP文档模板混合使用

页面级服务（只提供控制台），文档规范参考：页面类服务doc模板

SP文档包含：

  • 产品介绍；

  • 快速启动（如何对接本服务、最小demo示例、demo示例用到API或控制台操作说明）；

  • API文档；

  • SDK文档；

# 文档自动发布教程及格式规范

AECORE为各个服务准备了git仓库，用于管理和发布各SP文档，目前文档支持提交主干自动更新，同时每次更新都会将上一次版本备份。每个SP负责人默认拥有其对应repo的权限，其他人需要权限请通过公司工作流申请。

文档格式规范说明：

  • 文档命名：

1、产品文档统一以：product开头，格式product_1_xxx（如：product_1_info），如果有多篇产品文档，只修改数字和xxx，数字按顺序增加 1、2、3、4、.....

2、快速启动统一以：guide开头，格式 guide_1_xxxx，如果有多篇产品文档，只修改数字和xxx，数字按顺序增加 1、2、3、4、.....

3、API文档统一以：api开头，格式api_1_xxxx

4、SDK文档统一以：sdk开头，格式sdk_1_xxxxx

如果每个大类都有多篇产品文档，只修改数字和xxx，数字按顺序增加 1、2、3、4、.....

  • 图片格式：

1、图片名字全局唯一；

2、图片命名全部英文小写；

3、图片后缀英文小写；

4、图片、链接地址写相对地址；语法：

5、请勿用图片做为标题

下面将介绍文档自动发布操作流程：

一、从master仓库pull代码，并新建分支，修改提交到最新分支。

二、通过提PR的形式，将新分支的内容merge到master分支。即可完成自动化发版。

注意：严格按照md语法编写，语法错误会导致文档发布失败。当前线上的文档都是格式调成好的，大家未来更新的时候可参考原有格式。

1、 创建PR

2、 merge到master分支

# swagger文档导入生成API文档教程

Java项目并且使用swagger，编写API文档我们支持通过swagger导入生成，具体操作步骤如下：

一、通过接口导入swagger文件（必须在公司内网）

POST http://10.5.2.175:8888/swaggerToMd?resourceId={resourceId}&updateFiles={updateFiles}
1

resourceId为服务英文标识即git仓库名称（注意全部为小写）

updateFiles为需要导入的json文件（swagger的更新为全量更新）

同时也支持通过命令行导入

curl --location --request POST 'http://10.5.2.175:8888/swaggerToMd' \

--form 'resourceId=demo-sp' \

--form 'updateFiles=@/Users/liujiawang/Desktop/api.json' \

--form 'updateFiles=@/Users/liujiawang/Desktop/file.json'
1
2
3
4
5
6
7

二、swagger导入后会自动生成md文件，并且会在git仓库创建分支保存此文档，此时如果需要发布，只需要提交PR，merge到master主干，即完成发布。

# 发布portal页以及isv控制台

# 接收isv的订阅与调用

SP入驻portal页以及isv控制台 →

  • 在线客服

  • 意见反馈