作為開發(fā)人員，我們在日常生活中經(jīng)常面臨的最繁瑣的任務(wù)之一就是編寫良好且易于理解的文檔。 無論我們的文檔只有幾行來解釋功能的核心功能，還是表明系統(tǒng)的來龍去脈的成熟文章都沒關(guān)系。 重要的是，我們試圖通過文檔傳達(dá)的信息是準(zhǔn)確且可理解的。

在上一篇文章中 ，我們討論了自動(dòng)REST API生成的主題。 更準(zhǔn)確地說，我們演示了如何使用Speedment的經(jīng)過改進(jìn)的Spring Integration插件為您的數(shù)據(jù)庫生成完整的CRUD REST API。

今天，我們將使這一知識(shí)更進(jìn)一步，并演示如何通過一次單擊即可為REST API生成交互式文檔。

如果您沒有機(jī)會(huì)使用Speedment Spring插件，我們強(qiáng)烈建議您閱讀上一篇文章，因?yàn)樵撐恼掳裱局改系谋匾畔ⅰ?

您喜歡Java Streams嗎？

如果對這個(gè)問題的回答是“是！”，“絕對！” 或“哎呀！”，那么Speedment是適合您的工具。 Speedment是Java ORM工具箱和運(yùn)行時(shí)，它使用純Java Streams作為應(yīng)用程序和數(shù)據(jù)庫之間的接口。

除了已經(jīng)熟悉的Streams API之外，Speedment還為最終用戶提供了圖形化工具，以便在幾秒鐘內(nèi)生成數(shù)據(jù)庫的Java表示，從而使他們完全可以停留在僅Java的環(huán)境中。

如果您想進(jìn)一步了解Speedment，請前往
文檔頁面上 ，您將找到大量指南和示例。 在本文的其余部分，我們將重點(diǎn)介紹Speedment的Spring插件的新更新。

開始之前

為了生成REST API文檔，Speedment使用了OpenAPI規(guī)范和Swagger UI的組合。

根據(jù)您是否從頭開始，準(zhǔn)備步驟會(huì)有所不同，但是無論起點(diǎn)如何，最終結(jié)果都是相同的。

如果您已按照上一篇文章中的指南進(jìn)行操作，我們在其中解釋了如何使用Speedment生成REST API，則只需向項(xiàng)目的pom.xml文件添加幾個(gè)依賴項(xiàng)：

< 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 >

另一方面，如果您是從頭開始的話，請轉(zhuǎn)到Initializer ，在這里您將能夠在Spring支持下生成Speedment項(xiàng)目。 到達(dá)Initializer后，將為您提供大量用于配置項(xiàng)目的選項(xiàng)。 一個(gè)特別重要的配置選項(xiàng)是Initializer的Plugins部分。

要在新的Speedment項(xiàng)目中啟用Spring支持，請選中“ Spring”選項(xiàng)旁邊的復(fù)選框。 對項(xiàng)目配置滿意后，繼續(xù)并單擊初始化器底部的“下載”按鈕。

準(zhǔn)備就緒后，可以通過從項(xiàng)目模板的根文件夾執(zhí)行以下命令來啟動(dòng)Speedment Tool：

mvn speedment:tool

如果正確安裝了插件，則會(huì)看到一些特定于Spring Boot的選項(xiàng)，可用于配置REST API和文檔。

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

昂首闊步的自動(dòng)機(jī)

對于以下示例，我們將使用MySQL示例數(shù)據(jù)庫Sakila。 您可以將其下載為獨(dú)立實(shí)例或Docker容器。

當(dāng)您打開Speedment Tool并成功連接到數(shù)據(jù)庫時(shí)，將為您提供一個(gè)用戶界面，其中包含有關(guān)數(shù)據(jù)庫的元數(shù)據(jù)信息以及一些您可以配置的選項(xiàng)：

如果單擊頂部橫幅中的“ Generate”按鈕，將生成數(shù)據(jù)庫的Java表示。 要為您的REST API生成文檔，必須啟用在項(xiàng)目視圖中找到的“生成REST文檔”選項(xiàng)（可通過選擇樹中的頂部節(jié)點(diǎn)來訪問該選項(xiàng)）。

啟用后，其他配置選項(xiàng)將變?yōu)榭捎?#xff0c;使您可以進(jìn)一步自定義生成的文檔：

下次重新生成Spring項(xiàng)目時(shí)，將生成一些特定于OpenAPI的配置。 為了查看和使用生成的文檔，您需要運(yùn)行Spring應(yīng)用程序。 為此，執(zhí)行以下命令：

mvn spring-boot:run

一旦您的Spring應(yīng)用程序啟動(dòng)并運(yùn)行，您就可以在以下端點(diǎn)http：// localhost：8080 / swagger-ui.html上找到生成的Swagger文檔。

根據(jù)您配置項(xiàng)目的方式，在生成的文檔中可能會(huì)看到不同的結(jié)果。 例如，如果禁用某個(gè)表的REST API生成，則下次重新生成項(xiàng)目時(shí)，該表的端點(diǎn)將在文檔中不可用。

借助生成的Swagger文檔，您可以立即了解您的應(yīng)用程序已注冊了哪些REST終結(jié)點(diǎn)，每種終結(jié)點(diǎn)可使用的HTTP方法，并直接從Swagger UI對這些終結(jié)點(diǎn)執(zhí)行HTTP請求：

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

注意：連接到Swagger端點(diǎn)時(shí)，如果出現(xiàn)以下提示，請確保您的Spring入口點(diǎn)位于正確的程序包中（必須在Swagger配置所在的程序包上方或相同的程序包中）：

通常，這表明Spring未掃描您的Swagger配置。

摘要

編寫良好且易于理解的文檔可能是一個(gè)漫長而乏味的過程。 借助Speedment的Spring Boot插件的新更新，用戶可以在幾秒鐘內(nèi)為其REST API生成交互式文檔。

資源資源

文章“如何快速生成整個(gè)數(shù)據(jù)庫CRUD REST API”

Speedment Initializer能夠生成項(xiàng)目模板 在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

總結(jié)

以上是生活随笔為你收集整理的Java / Spring：如何快速生成整个Swagger记录的CRUD REST API的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。