API 网关知道自己被配置来处理哪些主机、路径、方法、策略和上游，因此是很有价值的 API 发现证据来源。但它不是完整的 API 清单，也无法仅凭流量或路由生成可信文档。
可靠的治理方案需要核对四种视图：经过审查的 API 契约、有效网关状态、实际暴露与流量，以及归属清单。文档应由获批契约与指南发布，差异则进入有负责人的漂移处理流程，而不是悄悄改写源文件。
核心要点
- 把网关配置与流量视为观测证据，而不是唯一事实来源。
- 为每个 API 指定负责人、受众、环境、版本、数据分类、生命周期状态和退役计划。
- 使用经过审查的 OpenAPI 描述和人工编写的指南发布参考文档。
- 核对各来源中缺失、意外、重复、过期和不可达的 API。
- 按策略分开公开、合作伙伴、内部和管理类目录。
- 在网关、DNS、上游、门户、客户端和数据层共同验证退役结果。
明确“已发现”的含义
不同来源回答不同问题：
| 来源 | 能说明什么 | 无法单独证明什么 |
|---|---|---|
| OpenAPI 仓库 | 预期操作、Schema、安全契约和版本 | 契约已部署或准确 |
| 网关配置 | 有效路由、插件、上游和暴露设置 | 未记载的内部调用或应用行为 |
| 流量观测 | 主机、路径、方法、状态、流量和活跃客户端 | 合法归属、完整 Schema 或安全授权 |
| 服务目录 | 负责人、系统、环境、数据分类和生命周期 | 每个端点都只按记录方式可达 |
| 开发者门户 | 获准消费者能够找到和阅读的内容 | 隐藏、影子、已退役或直连后端的暴露面 |
| DNS、负载均衡器与云清单 | 能从外部或内部访问的表面 | API 语义和策略正确性 |
发现流程应该创建候选项或差异项，而不是自动发布 API。观测到的流量可能来自扫描器、错误路径、私有数据或过期客户端。
核对四种视图
1flowchart LR
2 C[经过审查的 OpenAPI 与指南] --> R[核对服务]
3 G[有效网关清单] --> R
4 T[观测到的主机、路径、方法和客户端] --> R
5 O[归属与生命周期目录] --> R
6 R --> D[带负责人和严重程度的漂移队列]
7 R --> P[获批文档版本]
8 P --> X[公开、合作伙伴或内部门户]
9 D -->|经审查的修正| C
10 D -->|经审查的网关变更| G核对服务只负责比较证据，不会把运行时状态自动复制回源文件，也不会自动发布观测流量。每项修正都应由存在缺陷的制品负责人处理。
构建清单记录
使用稳定标识符，而不要只依赖显示名称。一条实用的记录应包含：
- API 与操作 ID；
- 负责团队和 On-call 联系方式；
- 业务用途和受支持消费者；
- 公开、合作伙伴、内部或管理类受众；
- 环境、区域、主机名、基础路径和协议；
- 契约版本与网关配置版本；
- 认证方式、粗粒度授权和敏感数据分类；
- 上游服务与绕过控制；
- 生命周期状态：提议、活跃、弃用、退役或例外；
- 弃用日期、替代版本、最后观测使用时间和退役负责人；
- 文档 URL 与最近一次验证结果。
OWASP API Security Top 10 2023 把清单管理不当列为风险，其中包括主机、环境、版本、文档和退役状态不清。因此，API 清单是运维安全控制，而不只是门户索引。
把 OpenAPI 作为参考契约
OpenAPI 3.1.2定义了一种与编程语言无关的描述方式，让人和计算机理解 HTTP API 表面。OpenAPI Description 可以为参考文档、验证、测试和客户端工具提供输入。
它仍然需要审查。应对照实际部署行为验证路径、方法、参数、Schema、响应、服务器、安全要求、示例和外部引用。OpenAPI 还警告，外部资源可能不可信、引用循环可能耗尽工具资源，而且 Markdown 或 HTML 字段必须经过清理。
Operation Object 的 deprecated 布尔值默认为 false。设为 true 时，它会告知消费者应避免使用该操作；设为 false 或省略时，文档并不承诺无限期支持。两条路径都不会在网关关闭路由，退役仍需单独执行流量与生命周期操作。
参考文档只是其中一层。还需要补充面向任务的快速入门、认证配置、错误处理、限制、示例、变更日志、迁移指南、支持渠道和状态信息。配套文章 使用 OpenAPI 编写 API 文档进一步介绍契约编写流程。
安全收集网关证据
Apache APISIX 3.19.0 的 Admin API暴露 Route、Service、Upstream、Consumer、证书等配置资源。即使只读，访问该 API 仍属于高权限操作：配置可能泄露内部主机、插件设置、身份结构和机密信息引用。
应使用受限运维网络和托管凭据，只导出清单所需字段，脱敏机密信息，并记录源集群、版本和采集时间。成功读取只能说明所选控制面返回了什么，无法证明所有数据面都已应用相同版本，也无法证明不存在绕过网关的上游直连。
可以把路由证据标准化为如下稳定字段：
1{
2 "gateway_cluster": "prod-eu-a",
3 "route_id": "orders-v2-get",
4 "hosts": ["api.example.com"],
5 "methods": ["GET"],
6 "paths": ["/v2/orders/*"],
7 "service_id": "orders-v2",
8 "observed_config_revision": "sha256:example",
9 "collected_at": "2026-09-22T00:00:00Z"
10}这是清单数据结构，不是 APISIX Admin API 响应 Schema。摘要只是占位符，必须替换为运维人员实际掌握的发布证据。
先给漂移分类，再修复
| 差异 | 可能的负责人 | 安全的后续操作 |
|---|---|---|
| 契约中的操作未出现在网关 | 交付或发布负责人 | 新建路由前先确认环境与发布意图 |
| 网关路由未出现在契约 | API 与平台负责人 | 判断它是内部、应急、过期还是影子路由 |
| 已弃用版本仍有流量 | 产品与客户端负责人 | 找到获准客户端并执行迁移计划 |
| 门户页面指向旧契约 | 文档负责人 | 从获批版本重新构建，并验证链接与示例 |
| DNS 或负载均衡器绕过网关 | 网络与服务负责人 | 关闭替代路径，或显式纳入治理 |
| 负责人缺失或无法联系 | 平台治理团队 | 升级处理；必要时限制暴露，并分配负责人 |
不要自动删除意外路由。它可能是获得授权的事故应急措施。应记录操作者、目的、到期时间和跟进项，再通过审查完成核对。
面向目标受众发布
目录可见性和运行时授权是两种不同控制。隐藏门户页面不会保护路由，发布文档也不会授予访问权限。
在 API7 Enterprise 3.10.x 中，API Product可以把网关 Service 组合为开发者门户中的产品，并根据关联的 OpenAPI 规范生成文档。该文档区分了网关产品与外部产品：外部产品不由 API7 Gateway 代理，也不使用相同的订阅或凭据路径。这是特定产品与版本的发布选项，不是 Apache APISIX 开源版能力。
发布前应确认：
- 产品只包含预期的 Service、主机和版本；
- 可见性符合公开或已认证受众策略；
- 认证说明与已部署网关一致；
- 示例使用非生产占位符，并能在目标沙箱中成功；
- 限制、错误响应和弃用通知均为最新；
- 不包含内部名称、机密信息引用和敏感 Schema；
- 门户版本能够关联到获批契约版本。
把 API 退役作为多系统变更
弃用用于传达意图，退役用于终止受支持的使用。受控退役应完成以下步骤：
- 识别客户端和负责人，但不要把相关性字段当成可信身份；
- 发布替代方案与截止日期；
- 在适用时停止发放新的订阅或凭据；
- 监控允许的遗留使用并联系负责人；
- 在批准时间删除或拒绝网关路由；
- 关闭 DNS、负载均衡器和上游直连暴露；
- 删除门户页面或将其标记为归档证据；
- 验证旧流量按设计失败，而且保留数据符合策略。
保留决策与最终检查的审计证据。某条路由近期没有流量，并不能证明没有客户端依赖它；必须考虑观测窗口、季节性使用和遥测缺失。
发现与文档检查清单
- 每个活跃 API 是否都有明确负责人和支持渠道？
- 契约、网关、流量和目录版本是否分别记录？
- 清单能否区分公开、合作伙伴、内部和管理类暴露？
- 外部 OpenAPI 引用是否固定、受限且经过清理？
- 观测路径是否被当作候选项，而不是自动发布的 API？
- 高权限网关配置是否脱敏并受到访问控制？
- 每个漂移项是否指出有缺陷的制品及其负责人？
- 门户可见性与网关授权是否始终作为独立控制？
- 弃用是否包含客户端证据、替代方案、截止日期和退役操作？
- 路由删除后是否检查了绕过暴露？
常见问题
网关能否生成完整的 API 文档？
不能。它可以提供路由和策略证据，但通常缺少完整 Schema、领域语义、示例、错误含义和用户任务。
是否可以安全地自动发布从流量中发现的 API？
不能。流量可能包含无负责人、恶意、错误、私有或已弃用的路径。应先分诊，再将它映射到获批契约与负责人。
是否应该把网关导出作为事实来源？
通常不应该。把经过审查的契约和策略保留为期望状态，把网关导出作为用于核对的观测状态。
后续步骤
将清单连接到 OpenAPI 驱动的网关运维、API 文档编写和治理式 API 交付。