哈喽各位同學們大家好呀，假期大家休息的怎麼樣？放假回來上班的第一天小編繼續大家分享開發者學院中課程“Spring Boot 2.5實戰API幫助文檔Swagger”幹貨總結哦~Spring Boot 2.5.x開發實戰可是Java中級工程師必備課程！
課程連結以及圖譜位址小編已經為大家指路了，搭配學習效果更佳👇
課程名稱：Spring Boot 2.5.x開發實戰
課程位址：
https://developer.aliyun.com/learning/course/71?spm=a2c6h.21254954.0.0.4e905907uoWZzr圖譜名稱：Alibaba Java 技術圖譜
圖譜位址：
https://developer.aliyun.com/graph/java?spm=a2c6h.21110250.J_5703890090.6.700e3c67EjOBeJSpring Boot 2.5實戰API幫助文檔Swagger
一、REST API幫助文檔
目前大型移動網際網路平台，像淘寶、微信，抖音、拼多多，包括滴滴打車、美團等，都是前後端分離的架構，我們叫微服務架構。
Swagger是自動化API文檔的生成工具，這個工具之前是Spring Boot項目來進行內建，現在使用Spring Boot項目做後端開發，寫API的代碼的機會比較多，咱們把這個工具給大家介紹一下。
作為一個快速開發架構，是Spring Boot提供了自己的一套API的文檔工具，目前來看，Swagger使用比較多，這幾年來普及率非常高，因為它非常友善，它的文檔生成基本上都是自動化，隻需要加一個簡單的處理就可以。
對于後端開發來說，不需要自己專門寫一套word文檔，發給前端，前端再自己去測試，再調進來背景API。Swagger文檔部署完以後，前端可以直接拿到，然後進行線上調試，非常友善。簡化前後端協助，協助避免出錯。
二、REST API自動生成幫助文檔Swagger
官網
https://swagger.ioSwagger自動化文檔工具
1. Swagger是一個完整的API生态，工具，規範，代碼生成。
2. 用于描述，生成，使用和可視化RESTful Web服務。
3. Swagger API project 2011 Tony Tam創立 最早Java版。
4. SmartBear Software公司支援，Apache License 2.0。
5. OpenAPI Spec。
6. Swagger and OAS。
7. Swagger 2 to OpenAPI 3。
8. 捐贈給linux基金會。
9. 行業标準規範。
10. Swagger Tools一套工具：設計、開發、測試、監控、治理。
Spring REST Docs
1. Spring REST Docs幫助自動化生成RESTful服務的文檔。
2. 使用Asciidoctor編寫的手寫文檔
3. Spring REST Docs為RESTful服務生成準确且可讀的文檔。
4. 将手寫文檔與使用Spring測試生成的文檔片段相結合。
5. 不受Swagger等工具生成的文檔的限制。
6. 它可以生成準确，簡潔和結構良好的API文檔。
7. Spring REST Docs支援測試驅動Test Driven。
8. Spring REST Docs支援Spring MVC Test架構，Spring WebFlux的 WebTestClient或REST Assured 3測試驅動。
9. Spring Boot 提供了注解@AutoConfigureRestDocs
10. 替代SpringFox Swagger
優點
1. 手寫文檔與使用Spring Test架構生成的文檔片段結合。
2. curl and http request snippets are generated。
3. easy to package documentation in projects jar file。
4. easy to add extra information to the snippets。
5. supports both JSON and XML。
MockMvc
1. MockMvc是Spring MVC Test工具類，支援Assert和Chain。
2. @Mock建立模拟對象，Mock。
3. @InjectMocks會自動将mock依賴注入測試對象。
4. MockitoAnnotations.initMocks（this）初始化。
5. MockMvcBuilders.standaloneSetup（..）.build（）通過注冊一個或多 個@Controller執行個體并以程式設計方式配置Spring MVC基礎結構來建構 MockMvc執行個體。
6. @Test 标注測試方法。
7. @WebMvcTest注解用于Spring MVC測試。 它禁用完全自動配置，而隻應用與MVC測試相關的配置。
8. WebMvcTest注解也自動配置MockMvc執行個體。
Asciidoctor插件步驟
1. pom.xml添加Asciidoctor插件
2. 添加對spring-restdocs-mockmvc的依賴
3. 配置屬性asciidocs輸出位置sourceDirectory
4. 配置測試任務task輸出位置outputDirectory
5. 配置asciidoctor task
6. snippets定義snippets輸出位置
7. 使task依賴于test任務，以便在建立文檔之前運作測試
8. 将snippets配置為輸入。将在此目錄下建立所有代碼段
REST Assured
1. Rest-Assured 由 Java 實作的 REST API 測試架構
2. 在Java中測試和驗證REST服務比在Ruby和Groovy等動态語言中更難。
3. REST Assured簡化REST API測試。
4. 專為測試 REST API 而設計的 DSL
5. Java DSL，用于輕松測試REST服務
6. REST Assured支援任何HTTP方法，但明确支援POST，GET，PUT，DELETE， OPTIONS，PATCH和HEAD，并包括指定和驗證例如 parameters, headers, cookies body 。
7. 自動化測試
8.
http://rest-assured.io/Spring Auto Rest Docs
Spring REST Docs 最低要求
1. Java 8
2. Spring Framework 5 (5.0.2 or later)
3. 此外, the spring-restdocs-restassured要求 :
4. REST Assured 3.0
Spring Rest Docs Demo
Spring Rest Docs實戰
Asciidocs Maven Plugins
Spring REST Docs可以線上友善的調試自己的API，但是沒有 Swagger 使用友善，這邊就簡單介紹下，重點還是講實戰Swagger。
Spring Boot 2.0 實戰Swagger
引用Swagger的包，需要自己做一些參數化的配置，簡單的可以在配置檔案進行，複雜一些配置需要在代碼裡面進行。生成的調試方式也比較簡單，生成的網頁裡面在詳細的檢索描述性，可以線上的發送get、Post等經典請求格式，很友善的去調接口，對于前後端分離的架構來說是很友善。
頁面打開兩種方式：
http://localhost:8081/swagger-ui.html
1. /v2/api-docs
2. Swagger UI /swagger-ui.html
接口文檔的版本可以不斷的變化，也可以在背景進行配置
Swagger-core 注解
在開發過程中，預設的話什麼都不加的話，實際解析的資訊如說控制器或者類别的基本資訊。如果希望對内加一些描述資訊。對原接口加原表述資訊的話，可以加進來如傳輸的資料類型，加個model的 API model加個說明，模組裡面字段你可以加property這個說明。操作具體方法的話可以operation，參數的話有pyramid的說明，應答消息和請求消息的話也可以加 response，這種相對的這些注解說明都可以了。它會自動的把這些資訊提取出來，生成放到Swagger線上幫助文檔裡。
Spring Boot 2.0 Rest API注解
應答消息401、404、403等消息可以自己定制，如整合API的類型的話，可以加入淘寶使用者的API接口等，根據自己的需求進行添加。
接口也可以分類，目前是這裡簡單做了幾個分類：訂單接口，使用者接口，并可以在裡面進行測試，友善線上檢查，并視圖形式，回報各個消息類型的結果。
測試有錯注意點：
需要使用RestController，不要是用Controller
出現order repository 問題，是沒有資料的原因
Swagger功能非常強大，也友善調試開發，尤其是前後端分離的架構。下節課繼續講Spring Boot的性能監控，内容容器等重要内容。