文章
借助 Atlassian Compass 搭建内部 API 目录
Katie Silver
Atlassian 首席产品经理
执行摘要
此处填写执行摘要
时间
4 分钟阅读。不到 10 分钟即可设置 Compass。
受众
您隶属于软件交付团队，日常使用各类 API。开发者、工程师等相关人员均可从中获益。
先决条件
- 获取 Compass - 免费试用，几分钟即可开始使用。
搭建精准的 API 目录是一项难题
过去十年间，我们逐步摒弃大型单体架构，转向微服务、分布式架构与自治团队模式。转型带来的益处显而易见，但随之而来的问题也同样突出。过去，类型化编译器和测试能够保障大型代码库各模块顺畅协作；而如今系统边界依靠 API 界定，一旦部署，各类 API 能否兼容协同往往难以预判。
我们深知，当所有人员都清楚 API 的工作机制及变更情况时，开发者的效率会更高，团队交付的产品质量也更优。难点在于跟踪并维护此类文档。
各组织在梳理自身服务方面的成熟度参差不齐。部分团队依靠 Slack 沟通，实现 API 提供方与使用方的信息对齐；另一些团队会在服务创建时记录 API 使用方式，但后续不再更新；若您具备完善的流程与工具，可为所有 API 建立文档，并将变更自动同步给其他利益相关者。
无论您处于哪个发展阶段，Atlassian 全新开发者平台 Compass 都能为您提供助力。
借助 Compass 实现 API 文档集中化管理
在微服务环境中，API 文档应当存放于何处？即便我们独立开发、部署各项服务，也并不希望每项服务都单独搭建有托管文档站点，或是将 OpenAPI 文件存放在难以查找的位置。团队希望整合所有相关信息并实现可检索，同时无需耗费大量内部人力搭建 API 注册中心。
使用 Compass，仅需一小时即可轻松完成全部 API 文档的集中化管理，而非耗时数周乃至一个季度。每次更新文档时无需手动上传，只需将 SCM（Bitbucket、GitHub 或 GitLab）接入 Compass 即可。
短短几分钟内，Compass 就会扫描所有代码存储库中的 OpenAPI 文件，并将其发布至您的目录。来自各个团队的所有 API 将即刻实现集中化管理与可检索。
查找 API 并与其集成
设想一名开发者接到一张请求单，需要搭建新的退款流程。他清楚需要找到合适的 API 来处理退款业务，却不知从何处着手。在很多企业中，他只能在 Slack 上四处询问，从而可能要等上数小时，才能等到身处地球另一端的同事回复该选用哪个 API。在使用 Compass 的团队中，所有这些工作均可自助完成。开发者可以搜索 API 端点，并在 Compass 中几秒钟内找到所需的确切信息。这意味着搜索信息的开发者能够更快找到所需内容，而拥有相关 API 的团队受到的干扰也会更少。
接收 API 变更通知
在微服务环境中，各项服务自主部署，有时会发生使用方需要知晓的变更方式。好在 Compass 不仅会收录您的 API 文档，还能持续追踪 API 的版本变更。每当同事合并更新 API 文档的拉取请求时，Compass 便会同步更新文档版本，确保版本开发者在 Compass 中查看的始终是最新版 API 信息。
历史变更记录甚至会展示在更改日志页面，方便您查看过往重要变更的发生时间：
完善的文档可助力开发者加快代码交付速度
Postman 近期开展的 API 开发者调研显示，52% 的开发者表示，在使用 API 时遇到的最大问题是文档缺失。文档缺失会拖慢开发进度、增加新工程师的上手难度，同时降低软件的可靠性。
如果您必须搭建专属的内部 API 目录，会是一项庞大工程，涉及繁杂的配套工作。而这些工作我们已为您完成，而集中式文档中心数分钟即可搭建完成。
为团队提供所需信息，见证交付效率飞速提升 🚀。