■一、Api2Doc
Api2Doc專注於RestfulAPI文檔的自動生成，它的原理是通過反射，分析Controller中的信息生成文檔。
■二、Api2Doc註解詳述
Api2Doc一共有3個註解：@Api2Doc、@ApiComment及@ApiError。
| No | 註解 | 說明 | ||||||||||||||||||||||||||||
| 1 | @Api2Doc | ◆@Api2Doc用於對文檔的生成進行控制。 ◆@Api2Doc修飾在類上，表示這個類會參與到文檔生成過程中，Api2Doc服務會掃描Spring容器中所有的Controller類，只有類上有@Api2Doc的類，纔會被生成文檔，一個類對應於文檔頁面左側的一級菜單項，@Api2Doc的name屬性則表示這個菜單項的名稱。 ◆@Api2Doc也可以修飾在方法，不過在方法上的@Api2Doc通常是可以省略，Api2Doc服務會掃描這個類的所有帶有@RequestMapping的方法，每個這樣的方法對應文檔頁面的左側的二級菜單項，菜單項的名稱取@RequestMapping的name屬性，當然您仍然可以在方法上用@Api2Doc的name屬性進行重定義。 |
||||||||||||||||||||||||||||
| 2 | @ApiComment | @ApiComment用於對API進行說明，它可以修飾在很多地方： 修飾在類上，表示對這組API接口進行說明。 修飾在方法上，表示對這個API接口進行說明。 修飾在參數上，表示對這個API接口的請求參數進行說明。 修飾在返回類型的屬性上，表示對這個API接口的返回字段進行說明。 修飾在枚舉項上，表示對枚舉項進行說明。 如果相同名稱、相同意義的屬性或參數字段，其說明已經在別的地方定義過了， 可以用 @ApiComment 的 seeClass 屬性表示採用指定類的同名字段上的說明信息。 |
||||||||||||||||||||||||||||
| 3 | @ApiError | @ApiError 用於定義錯誤碼，有的 API 方法在執行業務邏輯時會產生錯誤， 出錯後會在返回報文包含錯誤碼，以方便客戶端根據錯誤碼作進一步的處理， 因此也需要在 API 文檔上體現錯誤碼的說明。 | ||||||||||||||||||||||||||||
■三、項目實例
1)項目結構
2)pom.xml
※需要引入terran4j-commons-api2doc。網上最新版本是1.0.4，但是這個版本目前下載不下來。可下載最新版本爲1.0.2，對應這個版本的springboot版本爲2.0.4-2.0.9。
3)啓動類
※添加 @EnableApi2Doc 註解，以啓用Api2Doc服務。
4)Controller類
5)實體類
6)生成API文檔 http://localhost:8080/api2doc/home.html
■getUser
■updUser
