大摇大摆的最佳实践答案

【问题标题】：Swagger best practices大摇大摆的最佳实践
【发布时间】：2016-10-15 09:31:42
【问题描述】：

我目前正在定义一个 Rest API，我打算使用 Swagger 来记录它。我已经开始在 Swagger-Editor 中使用 YAML 中的 Open Api Specification 定义我的 API 规范。

然后，我知道我会将该文件提供给 Swagger-codegen 以生成服务器实现，并提供给 Swagger-UI（其静态文件将之前粘贴到我的服务器）以公开交互式文档。

根据 Swagger 的说法，这是自上而下的方法。

但稍后，我可能需要修改这个 API，我想通过之前定义的这个乏味的 YAML 文件来完成它，以使任何人都可以轻松地修改这个 API（并且与语言无关）。

这样做的方法是修改定义文件，然后重新使用 Swagger-codegen 吗？通过这种方法，我想我什至不能直接在实现服务器代码中轻易修改 API，而不会冒着文档过期的风险。

如果我选择使用 自下而上的方法（通过 Swagger-core 注释），我将限制我的所有进一步修改发生在实现服务器代码中，并且我的初始定义文件将永远无法再次使用。

所以另一个问题是：当我们想通过规范文件和实现服务器代码修改 API 时，是否有一种通用的方法来处理 Swagger（我想 Swagger-core 可以从我的代码中生成我，永远不会像我最初手动定义的那样）。

【问题讨论】：

标签： swagger

【解决方案1】：

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

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

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

自上而下的迭代违背了代码维护的目的。样板和自生成代码是为了让您快速入门，而不是为了维持生计。

【讨论】：

感谢您的回答，我认为它很适合我计划使用它的方式，您的评论证实了我。
“自顶向下的迭代方式违背了代码维护的目的。” 不同意这一点。理想情况下生成的代码不需要维护。只要可以将生成的代码和实现代码分开，然后重新生成。如果我将新端点添加到我的 api，我不想为它们编写样板代码，而我可以添加定义并重新生成

【解决方案2】：

我的意见可能有偏见。

对于 API 客户端，在大多数情况下应该不需要自定义它。如果您发现需要对其进行自定义以满足您的要求，可能值得通过https://github.com/swagger-api/swagger-codegen/issues/new 开始讨论（还请检查可用于自定义输出的选项，例如对于 PHP，运行java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php）

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

免责声明：我是 Swagger Codegen 的主要贡献者

【讨论】：

是的，对于服务器存根再生，这本来很方便（如 cxf wsdl 生成的类），但根据官方 Swagger 代码生成直接提供方法端点（使用 '//do some magic这里'）而不是接口，我猜他们不打算那样使用它。我错了吗？
我们还没有为服务器存根实现这一点。如果您想提供帮助，请在github.com/swagger-api/swagger-codegen 中打开问题或 PR
@wing328 在迭代 yaml（开发期间）文件并重复代码生成且不丢失实现时，是否有使用生成的（.NET Core）服务器存根的最佳实践？使用生成的代码时，有没有好地方可以询问 swagger-gen 最佳实践？
请加入github.com/swagger-api/swagger-codegen/issues/5431的讨论
我意识到这个问题已经有几年的历史了，但我刚刚使用 swagger code gen 实现了为服务器生成样板。我不需要手动触摸生成的代码。实际上，我什至没有将生成的代码签入到 git，只是签入 swagger 文件和生成参数（在我的情况下，在 pom.xml 中一些我使用 swagger maven 插件生成）-加上实际的业务逻辑实现代码当然！ .使用带有 Spring Boot 库和委托模式的 Java Spring 模板。生成代码和实现代码的单独源文件夹。