软创互联

API设计


#1

工具:API Blueprint 在线Editor

示例代码:https://gitlab.gugud.com/suyuxp/cert-sync.git

效果: https://api.gugud.com/cert-sync/

API设计内容要求

# 内容 描述 编写阶段 完善阶段
1 描述 基本功能简介 设计 开发
2 联系人 开发与运维的负责人 设计 部署
3 术语说明 本任务中涉及的业务术语 设计 开发
4 结构示意图 软件模块结构与依赖关系图 设计 开发
5 数据流向图 / 设计 开发
6 依赖项 涉及到的第三方应用与接口 设计 部署
7 服务清单 REST 与 MQ 等的服务目录与接口设计明细文档 设计 开发
8 工具明细 开发用编程语言、框架、数据库等 设计 开发
9 测试 测试计划、样本数据及测试脚本(设计阶段非必须) 设计 开发
10 安全 安全保障计划,灾备方案 设计 部署
11 归档位置 代码库与容器的命名计划 设计 部署
12 部署位置 部署方案、部署脚本(设计阶段非必须) 设计 部署
13 常见问题 常见问题的应对方案 部署 /
14 风险分析 对未来风险的可能项判断及等级评估 部署 /

API URL 约定

约定

  • API_BASE_URL=https://api.gugud.com
  • API文档URL(API_DOC_URL) = API_BASE_URL + 项目名称或用户名 + 代码库名称 + doc
  • API Mock的URLL(API_MOCK_URL) = API_BASE_URL + 项目名称或用户名 + 代码库名称 + mock
  • API实现的URL(API_URL) = API_BASE_URL + 项目名称或用户名 + 代码库名称

样例

API设计文档:https://api.gugud.com/code-manage/code-asset/doc/
API Mock:https://api.gugud.com/code-manage/code-asset/mock/
API 实现:https://api.gugud.com/code-manage/code-asset/

资料


#2

使用Api-blueprint文档创建mock server