SpringBoot中使用Swagger的超簡單方法
Swagger號稱世界上最流行的Api框架,它是RestFul 風格的Api。文檔在線自動生成工具:Api文檔與API定義同步更新。可以直接運行,能在線測試API接口;支持多種編程語言:(Java、PHP等)。
官網:https://swagger.io/
springBoot使用swagger太麻煩,每次都需要編寫config?如果我告訴你有這麼一種方式,你隻需要配置yml文件,你學還是不學?
整合Swagger
依賴:
<!-- Swagger --> <dependency> <groupId>com.battcn</groupId> <artifactId>swagger-spring-boot-starter</artifactId> <version>2.1.5-RELEASE</version> </dependency>
我這裡的Swagger大傢應該也發現瞭,並非是官方的,這個是第三方整合的,配置更加簡單。
配置詳解
詳細配置:
spring: swagger: enabled: true title: 標題 description: 描述信息 version: 系統版本號 contact: name: 維護者信息 base-package: swagger掃描的基礎包,默認:全掃描(分組情況下此處可不配置) #全局參數,比如Token之類的驗證信息可以全局話配置 global-operation-parameters: - description: 'Token信息,必填項' modelRef: 'string' name: 'Authorization' parameter-type: 'header' required: true groups: basic-group: base-package: com.battcn.controller.basic system-group: base-package: com.battcn.controller.system
我的配置
spring: swagger: title: 星空小屋 - 文章微服務接口 description: 文章微服務相關接口,包括文章、模塊、知識點管理等 version: 1.0.0 - SNAPSHOT contact: name: cv大魔王 email: [email protected] host: localhost enabled: true security: filter-plugin: true # 配置賬號密碼 username: root password: root
配置攔截器,後面有攔截器配置,如果有讀者需要在自己的項目使用,請原有的攔截器配置中修改,忽略掉以下路徑,以免被攔截導致無法訪問。“swagger-ui.html”, “static/css/“, “static/js/”, “swagger-resources”, “/**/error”, “v2/api-docs”
測試使用
運行項目,訪問IP+端口號/swagger-ui.html
,例如在瀏覽器訪問:http://127.0.0.1:13001/swagger-ui.html
登錄後的效果:
復習——常用註解
對swagger熟悉的小夥伴的請忽略“常用註解段落”
`@Api`:用在 Controller 類上,描述該類的作用 1. `value`="描述信息" 2. `description`="詳細描述該類的作用"
@ApiOperation
:用在 Controller 請求方法上,描述方法的作用。
@ApiModel
:用在請求參數是對象上,描述該對象類的作用
// 在對象類上使用@ApiModel @ApiModel(value="CategoryREQ對象", description="類別查詢條件") public class CategoryREQ extends BaseRequest<Category> { }
@ApiModelProperty
:用在請求參數是對象的屬性上,描述對象屬性的作用。
value
:屬性的描述hidden
:是否是查詢條件屬性, false:(默認值)在api文檔顯示,作為查詢條件;true 隱藏,不是條件屬性
// 請求方法參數是 CategoryREQ 對象 public Result search(@RequestBody CategoryREQ req) {} @ApiModel(value="CategoryREQ對象", description="類別查詢條件") public class CategoryREQ extends BaseRequest<Category> { @ApiModelProperty(value = "分類名稱") private String name; @ApiModelProperty(value="狀態(1:正常,0:禁用)") private Integer status; }
@ApiResponses
:用在請求的方法上,用於表示一組響應@ApiResponse
:用在@ApiResponses
中,一般用於表達一個錯誤的響應信息,註解參數:code
:數字,如 400message
:信息,如 “參數填寫錯誤”response
:拋出異常的類
@ApiIgnore
: 使用該註解忽略這個 API
@ApiImplicitParams
:用在請求方法上,對多個請求參數增加描述
@ApiImplicitParam
:可單獨使用,或在 @ApiImplicitParams 中使用,給方法的一個請求參數增加描述。
name
:參數名value
:描述參數的作用dataType
:參數類型,參數類型,默認String,其它值 dataType=“Integer”defaultValue
:參數默認值required
:參數是否必傳(true/false)paramTpye
:指定參數放在哪些地方(header/query/path/body/form)
header
:參數在request headers 裡邊提交 @RequestHeader
query
:直接跟參數完成自動映射賦值 @RequestParam
path
:以路徑變量的形式提交數據 @PathVariable
body
:以流的形式提交 僅支持POST(不常用)
form
:以form表單的形式提交 僅支持POST (不常用)
參考:
// 請求方法有多個請求參數 size, current @ApiImplicitParams({ @ApiImplicitParam(name="current", value="頁碼", required=true, paramType="path",dataType="int"), @ApiImplicitParam(name="size", value="每頁記錄數", required=true, paramType="path",dataType="int") }) @ApiOperation("根據分類名稱與狀態查詢分類列表接口") @PostMapping("/search/{current}/{size}") Result search(@RequestBody CategoryREQ req, @PathVariable int current, @PathVariable int size);
到此這篇關於SpringBoot中使用Swagger的超簡單方法的文章就介紹到這瞭,更多相關SpringBoot使用Swagger內容請搜索WalkonNet以前的文章或繼續瀏覽下面的相關文章希望大傢以後多多支持WalkonNet!
推薦閱讀:
- 解決springboot引入swagger2不生效問題
- 關於Swagger註釋API的使用說明
- Swagger中@ApiIgnore註解的使用詳解
- Spring Boot中如何使用Swagger詳解
- springboot詳解整合swagger方案