Swagger 招摇过市的最佳实践

我目前正在定义一个RESTAPI，我打算使用Swagger来记录它。 我已经开始用YAML中的开放API规范在Swagger编辑器中定义API规范

然后，我了解到我将向Swagger codegen提供该文件以生成服务器实现，并将该文件提供给Swagger UI（其静态文件先前将粘贴到我的服务器上）以公开交互文档

根据斯威格的说法，这是一种自上而下的方法

但是稍后，我可能需要修改这个API，我想通过前面定义的这个冗长的YAML文件来修改它，以使API易于被任何人修改（并且语言不可知）

执行此操作的方法是修改定义文件，然后重新使用Swagger codegen？通过这种方法，我想我甚至不能轻易地直接在实现服务器代码中修改API，而不冒文档过时的风险

如果我选择了自底向上的方法（通过Swagger core注释），我将限制在实现服务器代码中进行进一步的修改，并且我的初始定义文件将不再可用

因此，另一个问题是：当我们希望通过规范文件和实现服务器代码修改API时，是否有一种处理Swagger的通用方法（我假设，Swagger core可以从我的代码生成的文件永远不会像我手工定义的初始文件）

---

为了维护API文档，我建议的最佳做法是采用混合方法

最初，当您必须进行批量开发时，采用自顶向下的方法。这将减少初始设置和编码工作。这是任何codegen背后的基本思想

然后，当涉及到维护API或每天（或每周）添加一些新的API时，请遵循自底向上的方法。您已经有了前面的代码，唯一需要做的就是添加更多的注释或API定义

---

重复地使用自上而下的方法无法达到代码维护的目的。锅炉板和自我生成的代码是为了给你一个快速的开始，而不是为了维持

我的观点可能有偏见

对于API客户端，在大多数情况下不需要自定义它。如果您发现需要对其进行定制以满足您的需求，那么可以通过以下方式展开讨论（同时请检查可用于定制输出的选项，例如，对于PHP，运行

java-jar模块/swagger-codegen cli/target/swagger-codegen-cli.jar配置帮助-l PHP

）

对于服务器存根，理想情况下，开发人员只需要关注业务/应用程序逻辑，并在添加/删除/更新端点时重新生成服务器存根（但我不认为所有服务器存根都可以实现这一点）

---

免责声明：我是Swagger Codegen的头号贡献者

谢谢你的回答，我认为它与我计划使用它的方式非常吻合，你的评论证实了我的观点。“自上而下的迭代方式违背了代码维护的目的。”不要同意这一点。理想情况下生成的代码不需要维护。只要生成的代码和实现代码可以分开，就可以重新生成。如果我将新端点添加到api中，我不想在可以添加定义并重新生成的情况下为它们编写锅炉板代码。是的，对于服务器存根的重新生成，这会很方便（如cxf wsdl生成的类），但根据官方的Swagger codegen直接提供方法端点（使用“//在这里做一些魔术”）而不是接口，我想他们没有计划这样使用它。我错了吗？我们还没有为服务器存根实现这一点。如果您想提供帮助，请在@wing328中打开一个问题或PR。在迭代yaml（开发期间）时，是否有使用生成的（.NET Core）服务器存根的最佳实践重复代码生成且不丢失实现的文件？在使用生成的代码时，有没有一个好地方可以询问swagger gen的最佳实践？请加入讨论，我意识到这个问题已经有好几年了，但我刚刚实现了使用swagger code gen为服务器生成锅炉板。我不知道事实上，我甚至没有将生成的代码签入git，只签入了swagger文件和生成参数（在pom.xml中，我使用了swagger maven插件生成一些代码）-当然还要加上实际的业务逻辑实现代码。