# 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的订阅与调用

  • 在线客服

  • 意见反馈