作为开发人员，我们在日常生活中经常面临的最繁琐的任务之一就是编写良好且易于理解的文档。 无论我们的文档只有几行来解释功能的核心功能，还是表明系统的来龙去脉的成熟文章都没关系。 重要的是，我们试图通过文档传达的信息是准确且可理解的。

在上一篇文章中 ，我们讨论了自动REST API生成的主题。 更准确地说，我们演示了如何使用Speedment的经过改进的Spring Integration插件为您的数据库生成完整的CRUD REST API。

今天，我们将使这一知识更进一步，并演示如何通过一次单击即可为REST API生成交互式文档。

如果您没有机会使用Speedment Spring插件，我们强烈建议您阅读上一篇文章，因为该文章包含遵循本指南的必要信息。

您喜欢Java Streams吗？

如果对这个问题的回答是“是！”，“绝对！” 或“哎呀！”，那么Speedment是适合您的工具。 Speedment是Java ORM工具箱和运行时，它使用纯Java Streams作为应用程序和数据库之间的接口。

除了已经熟悉的Streams API之外，Speedment还为最终用户提供了图形化工具，以便在几秒钟内生成数据库的Java表示，从而使他们完全可以停留在仅Java的环境中。

如果您想进一步了解Speedment，请前往
文档页面上 ，您将找到大量指南和示例。 在本文的其余部分，我们将重点介绍Speedment的Spring插件的新更新。

开始之前

为了生成REST API文档，Speedment使用了OpenAPI规范和Swagger UI的组合。

根据您是否从头开始，准备步骤会有所不同，但是无论起点如何，最终结果都是相同的。

如果您已按照上一篇文章中的指南进行操作，我们在其中解释了如何使用Speedment生成REST API，则只需向项目的pom.xml文件添加几个依赖项：

 < dependencies > ... < dependency > < groupId >io.springfox</ groupId > < artifactId >springfox-swagger2</ artifactId > < version >2.9.2</ version > </ dependency > < dependency > < groupId >io.springfox</ groupId > < artifactId >springfox-swagger-ui</ artifactId > < version >2.9.2</ version > </ dependency > ...  </ dependencies > 

另一方面，如果您是从头开始的话，请转到Initializer ，在这里您将能够在Spring支持下生成Speedment项目。 到达Initializer后，将为您提供大量用于配置项目的选项。 一个特别重要的配置选项是Initializer的Plugins部分。

要在新的Speedment项目中启用Spring支持，请选中“ Spring”选项旁边的复选框。 对项目配置满意后，继续并单击初始化器底部的“下载”按钮。

准备就绪后，可以通过从项目模板的根文件夹执行以下命令来启动Speedment Tool：

 mvn speedment:tool 

如果正确安装了插件，则会看到一些特定于Spring Boot的选项，可用于配置REST API和文档。

如果这是您第一次使用Speedment，则可能需要遵循“ Hello Speedment ”快速入门指南来熟悉工作流程。

昂首阔步的自动机

对于以下示例，我们将使用MySQL示例数据库Sakila。 您可以将其下载为独立实例或Docker容器。

当您打开Speedment Tool并成功连接到数据库时，将为您提供一个用户界面，其中包含有关数据库的元数据信息以及一些您可以配置的选项：

如果单击顶部横幅中的“ Generate”按钮，将生成数据库的Java表示。 要为您的REST API生成文档，必须启用在项目视图中找到的“生成REST文档”选项（可通过选择树中的顶部节点来访问该选项）。

启用后，其他配置选项将变为可用，使您可以进一步自定义生成的文档：

下次重新生成Spring项目时，将生成一些特定于OpenAPI的配置。 为了查看和使用生成的文档，您需要运行Spring应用程序。 为此，执行以下命令：

 mvn spring-boot:run 

一旦您的Spring应用程序启动并运行，您就可以在以下端点http：// localhost：8080 / swagger-ui.html上找到生成的Swagger文档。

根据您配置项目的方式，在生成的文档中可能会看到不同的结果。 例如，如果禁用某个表的REST API生成，则下次重新生成项目时，该表的端点将在文档中不可用。

借助生成的Swagger文档，您可以立即了解您的应用程序已注册了哪些REST终结点，每种终结点可使用的HTTP方法，并直接从Swagger UI对这些终结点执行HTTP请求：

如果不确定请求正文中需要什么，可以在文档底部“模型”部分下找到请求正文模型：

注意：连接到Swagger端点时，如果出现以下提示，请确保您的Spring入口点位于正确的程序包中（必须在Swagger配置所在的程序包上方或相同的程序包中）：

通常，这表明Spring未扫描您的Swagger配置。

摘要

编写良好且易于理解的文档可能是一个漫长而乏味的过程。 借助Speedment的Spring Boot插件的新更新，用户可以在几秒钟内为其REST API生成交互式文档。

资源资源

文章“如何快速生成整个数据库CRUD REST API”

Speedment Initializer能够生成项目模板 在GitHub上加速

s

Per Minborg
米斯拉夫·米利切维奇（MislavMiličević）

翻译自: https://www.javacodegeeks.com/2020/03/java-spring-how-to-generate-an-entire-swagger-documented-crud-rest-api-with-speedment.html