在软件开发的世界里，API规范是非常重要的一环。OpenAPI规范作为一种业界标准，被广泛应用于API设计和文档编写。然而，有些人试图通过从现有代码中生成OpenAPI规范来简化这一过程。虽然这种方法看似省时省力，但实际上可能带来更多的麻烦。
从代码生成OpenAPI规范的主要问题在于代码并非总能完全反映出API的整体结构和设计理念。代码可能存在冗余、不规范的命名、过度复杂的逻辑以及不一致的数据模型，导致生成的OpenAPI规范同样存在这些问题。此外，代码生成的规范通常缺乏必要的注释和文档，使得其他开发人员难以理解API的语义和用法。
另一个问题是代码生成的规范可能会隐藏一些潜在的设计缺陷和安全隐患。通过手动编写OpenAPI规范，开发人员可以更好地思考API的设计和安全性，并及时发现和修复潜在问题。而从代码自动生成规范则容易忽略这些细节，导致在后期出现严重的后果。
因此，虽然从代码生成OpenAPI规范在短期内可能看起来是一个快捷方便的方式，但从长远来看，手动编写规范仍然是更为可靠和有效的方法。只有通过仔细思考和精心设计，才能创建出符合标准和最佳实践的API规范，从而确保API的稳定性和可靠性。
了解更多有趣的事情：https://blog.ds3783.com/