在当今数字化时代，API（应用程序编程接口）规范化变得越来越重要。OpenAPI规范作为一种行业标准，帮助开发人员创建和设计优质的API。然而，最近有一种趋势正在崛起，即通过代码来生成OpenAPI规范。尽管这种方法可能看起来方便快捷，但我们认为停止从代码生成OpenAPI规范是至关重要的。
首先，从代码生成OpenAPI规范可能会导致不完整或不准确的文档。代码通常只反映了实际实现，而不一定反映出API设计的意图。由于API设计是一个复杂的过程，需要考虑到许多因素，包括可用性、安全性和可扩展性。只依靠代码来生成规范，很容易忽略这些重要方面，导致API文档的缺陷。
其次，从代码生成OpenAPI规范缺乏可读性和易用性。OpenAPI规范的目的是提供清晰、详细的API文档，以便其他开发人员能够轻松理解和使用。但通过代码生成规范往往会产生冗长、难以理解的文档，给开发人员造成困扰。相比之下，手动编写OpenAPI规范可以确保文档的简洁和易读性。
最重要的是，停止从代码生成OpenAPI规范有助于提高API设计的质量。通过手动编写规范，开发人员可以更好地思考和计划API的结构和功能。他们可以更好地理解业务需求，从而设计出更好的API。这种方式也有利于团队合作和沟通，确保所有人都能参与到API设计的过程中。
综上所述，我们呼吁停止从代码生成OpenAPI规范。相反，我们应该重视手动编写规范，以确保API设计的质量和准确性。只有这样，我们才能更好地满足用户的需求，实现API的最佳性能和可用性。
了解更多有趣的事情：https://blog.ds3783.com/