带有Swagger的Spring Rest API

带有Swagger的Spring Rest API –公开文档

创建API文档后，将其提供给涉众非常重要。在理想情况下，此发布的文档将具有足够的灵活性以解决任何最新更改，并且易于分发（就成本以及完成此操作所需的时间而言）。为了使这成为可能，我们将利用我在上一篇文章中完成的详细介绍API文档创建过程的内容。结合使用Swagger UI模块和json中已发布的API文档，我们可以创建可用于与API交互的简单HTML文档。

与Swagger UI集成

Swagger UI的开发者将其描述为HTML，Javascript和CSS资产的无依赖集合，可从与Swagger兼容的API动态生成漂亮的文档和沙箱。由于Swagger UI没有依赖关系，因此您可以将其托管在任何服务器环境或本地计算机上。话虽如此，让我们看一下如何将Swagger文档提供给Swagger UI。作为HTML，CSS和JS的静态集合，我们可以将其拖放到我们的项目中，而无需修改我们的pom.xml或项目中的任何其他文件。只需转到GitHub并下载最新文件即可。

完成后，只需提供指向您的API列表的链接。只需打开index.html并用您自己的默认API列表URL替换就可以了。我的示例中的URL看起来像这样： http://[hostname]:[port]/SpringWithSwagger/rest/api-docs 。保存此更改并部署应用程序和静态Swagger UI之后，您应该能够浏览API并与之交互。

API文档

根据我的示例，我可以访问以下URL http://localhost:8080/SpringWithSwagger/apidocs/ （由于我选择的部署方法的性质）。如您所见，Swagger UI仅使用以json格式发布的数据（先前已讨论）。您会看到的第一件事是API列表，它使您可以浏览已发布的API的集合。

api列表

当您要浏览可用的操作时，只需单击一下所有简短说明的所有精美彩色列表，便可以知道下一步的导航位置。颜色在整个清单中保持一致，并很好地补充了操作。

方法清单

当您找到所需的操作时，便该该首先获取您要查找的信息了。单击方法名称，将显示完整的方法说明以及参数和响应消息。但是还有更多原因，因为您可以使用自己的API并测试您的方法。提供所有必需的参数并点击“尝试一下！” 按钮，您可以检查您的应用程序服务器是否已启动并以预期的方式运行。如果您的代码需要某种类型的文件上传（就像我的更新用户的头像逻辑一样），那么Swagger UI会提供方便的工具来使其尽可能地容易。

即使您能够进行一些快速的即席测试或检查，此工具也绝对不适合应用程序测试。它所做的只是以一种易于阅读的方式提供API文档，如果您有需要的话，可以自己尝试该方法（以提高对文档的理解）。我发现这很不错，因为您需要了解一下操作本身，并且它的可观察到的行为Swagger UI可以使您满意，如下所示。

方法测试

擅长的地方

我真的很喜欢Swagger处理文档的方式以及Swagger UI呈现文档的方式。以下几点使Swagger非常适合我的API文档需求：

语言不可知
- 在异构环境中工作或考虑将新语言和工具引入您的项目时，该资产具有极大的价值。
基于注释的文档
- 批注将文档绑定到代码，以单个生命周期创建一个单元。这使得管理，发布和发布的整个过程变得更加容易，并允许进行自动化。
公开进行后期处理
- 拥有json形式的中间步骤可让开发人员将自定义脚本和转换器附加到流程中，以便根据涉众的需要生成各种格式的文档，例如PDF或Word文档。
丰富的模块和组件生态系统
- 如果浏览Swagger的可用模块和组件，您可能会惊讶于此工具花了多少时间。那里有许多有用的组件，因此很有可能会找到您认为您的项目可能需要或受益的Swagger扩展。
外观精美的UI工具
- 因为我在UI方面不是很有才华，所以我很高兴不必烦恼如何创建，格式化，呈现和交付文档的方式。我所需要的只是在源代码中提供相关信息，仅此而已。框架负责其余的工作，而我很快就得到了及时的文档。鉴于Swagger UI的性质，如果需要，可以很容易地向其添加自定义公司标识。
试试看！ 选项
- 小事总是让我开心。但是我认为，对整个团队来说，在文档中整齐地打包此选项（例如，在需要的地方，需要的时候）非常有益。

不足之处

我不会假装这是灵丹妙药，适合所有解决方案。当然，在某些情况下，此类工具不是首选。鉴于其年轻的年龄，仍有一些事情需要增加/改进。但重要的是要声明该项目仍在开发中，并且日渐流行。话虽这么说，我想指出一些我发现的问题，这些问题需要深入研究和其他工作。在我的第一次尝试中，我将重点关注三个主要问题。

有条件地访问某些模型参数
- 根据您的需求（以及使用的Swagger版本），您可能会发现自己需要从Swagger UI和Swagger json隐藏某些模型参数。但是，这比我预期的需要更多的工作，并且需要修改模型属性。可以预期，随着Swagger及其相关组件的下一个主要版本的发布，情况会变得更好，但是在此之前，您不得不手动执行此操作。如果您对如何实现此目标感兴趣，请查看我的下一篇名为Swagger的Spring Rest API –精调公开的文档。
文件上传及相关字段
- 您的某些API操作可能需要上传文件（例如我的头像更新方法）。但是，要使操作细节看起来像我的示例中所呈现的那样，需要一点点的手工工作和规范筛选。要摆脱与此问题相关的不需要的参数，请查看我的下一篇名为Swagger的Spring Rest API –精调公开的文档，我将在此详细介绍此问题以及如何在此处显示结果。
API模型和XML
- Swagger声称它是json和XML的朋友。在操作级别上肯定是正确的，但是，在模型表示方面，XML比json位居第二（由于与XML及其模式有关的技术复杂性）。当前，Swagger UI中的所有API模型都显示为json实体（json和XML），这迫使我不要在ProductsEndpoint文档中声明响应类型（在我的SpringWithSwagger示例中，示例使用XML格式的端点）。这是我尚未完全解决的问题，因此我有意选择在处理XML时不声明响应类型。

下一步是什么？

如果按照所有步骤进行操作，现在应该已经有适用于您的API的API文档/沙箱。在我的下一篇名为Swagger的Spring Rest API的文章中，我将展示如何使用Swagger来微调已发布的文档-微调公开的文档。该微型系列中使用的代码在GitHub上发布，并提供了所有讨论的功能和工具的示例。请享受！