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

image-20210221184645521

登錄後的效果:

image-20210221184734860

復習——常用註解

對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 中使用,給方法的一個請求參數增加描述。

  1. name:參數名
  2. value:描述參數的作用
  3. dataType:參數類型,參數類型,默認String,其它值 dataType=“Integer”
  4. defaultValue:參數默認值
  5. required:參數是否必傳(true/false)
  6. 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!

推薦閱讀: