Swagger最佳实践

Question

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

然后,我明白我将该文件提供给Swagger-codegen以生成服务器实现,并且还将Swagger-UI(其静态文件将先粘贴到我的服务器上)以提供交互式文档.

根据Swagger的说法,这是自上而下的方法.

但是后来,我可能需要修改这个API,我希望通过之前定义的这个繁琐的YAML文件来实现它,以保持API可以被任何人轻松修改(和语言无关).

1. 这样做的方法是修改定义文件,然后重新使用Swagger-codegen？通过这种方法,我想我甚至不能在实现服务器代码中直接修改API,而不会有过时的文档.

如果我选择采用自下而上的方法(通过Swagger-core注释),我将限制在实现服务器代码中进行的所有进一步修改,并且我的初始定义文件永远不会再次使用.

2. 所以另一个问题是:当我们想要通过规范文件和实现服务器代码修改API时,是否存在处理Swagger的常用方法(我想Swagger-core可以从我的代码中生成我的文件,永远不会像我手工定义的那样.

谢谢你的关注.

Answer 1

为了维护API文档,我建议的最佳行动方案是遵循混合方法.

最初,当你必须进行批量开发时,请采用自上而下的方法.这将减少初始设置和编码工作.这是任何codegen背后的基本理念.

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

自上而下迭代地失败了代码维护的目的.锅炉板和自生成的代码可以帮助您快速启动,而不是维持生计.

Answer 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 的最大贡献者