Zalando RESTful API 指南：OpenAPI规范发布范围详解

在Zalando的RESTful API设计指南中，第192条规则明确规定了API文档发布的要求。这条规则最初表述为"必须发布OpenAPI规范"，但经过社区讨论后，发现其实际适用范围需要更精确的描述。

规则背景与重要性

OpenAPI规范（原Swagger）已成为描述RESTful API的事实标准。它提供了机器可读的API定义，能够自动生成文档、客户端代码和测试用例。对于API开发者而言，维护一个准确、完整的OpenAPI规范文档是确保API易用性和可维护性的关键实践。

规则细节解析

原始规则标题简单表述为"必须发布OpenAPI规范"，但正文内容揭示了更细致的适用范围：

1. 对外API：面向外部开发者或第三方消费者的API必须(MUST)发布OpenAPI规范
2. 内部API：仅在公司内部使用的API可以(MAY)选择是否发布OpenAPI规范

这种区分非常重要，因为不同场景下的API有不同的文档要求和维护成本预期。对外API需要更严格的文档标准以确保良好的开发者体验，而内部API可以根据实际项目需求灵活处理。

规则优化建议

基于这一发现，社区建议将规则标题修改为"必须为外部API发布OpenAPI规范"，以更准确地反映规则的实际适用范围。这种精确表述有助于：

• 避免内部API开发者误解为强制性要求
• 明确区分不同API类型的文档标准
• 保持指南的清晰性和可执行性

实践建议

对于API开发者，我们建议：

1. 所有对外API都应维护完整的OpenAPI规范文档
2. 内部API可根据团队协作需求和工具链支持程度决定是否采用
3. 即使选择不强制要求内部API文档，仍推荐使用OpenAPI作为内部API的描述标准
4. 考虑使用自动化工具从代码生成OpenAPI规范，降低维护成本

通过这种分层次的文档策略，团队可以在保证外部API质量的同时，保持内部开发的灵活性。