先招摇或api

Question

我已经阅读了 swagger 的定义和格式，并理解使用 swagger 定义来描述 API。

先写swagger定义然后再写API会更好吗？还是先写API，然后大摇大摆？我没有这方面的经验，我想为应用程序编写一个 REST API 和一个 swagger 文件。

Answer 1

我认为顺序并不重要。这两种方法在 Swagger Getting Started Guide 中都被赋予了合法性。关键是一个应该从另一个生成，因此您不必手动维护两者。

在 cmets 中，cricket_007 已经提到存在用于从 swagger 定义生成 Web 服务框架的工具。使用这些工具，首先编写 swagger 定义是有意义的。这是入门指南中的自上而下的方法。

从上面链接的 Swagger 入门指南中，您可以看到还有一些工具可用于从 java 代码生成 Swagger 文档，前提是您使用的是 JAX-RS 等特定框架。这是自下而上的方法。

这取决于个人喜好。如果您是那种不想将您的代码库“耦合”到 Swagger 并确保您的应用程序不依赖 Swagger 工作的人，那么自下而上的方法是最好的。但是，如果您想完全接受 Swagger 工具链并真正“接受”它，那么自上而下的方法可能是最好的。

此外，如果这是出于教育目的，请考虑您想了解什么。如果您想学习如何从头开始编写 JSON REST API（或使用 JAX-RS 之类的东西），那么自下而上的方法会教您更多。但是，如果您的目标是尽可能多地了解 Swagger，那么自上而下的方法会更好。