Swagger文件使用

有很多人不清楚swagger ui的路徑，由於我們使用了更為好用的swagger-bootstrap-ui，實際上使網域名稱+埠 +/doc.html，如：http://localhost:8080/doc.html

在沒有swagger之前，我們需要自己手寫文件，手寫文件的出現問題：

文件更新時需要要與前端人員進行對接，文件存在更新不及時

介面文件多，沒有進行分組管理，增加管理難度

介面說明與返回結果不明確

而通過swagger就能輕鬆解決這些問題，而且spirngboot整合swagger也相對簡單

swagger官網

io.springfox springfox-swagger2 1.9.3 com.github.xiaoymin swagger-bootstrap-ui 2.9.2

在yami-shop-api工程中的config檔案下，有swagger相應的配置類，只要了解具體能配置哪些東西就好了，畢竟這個東西配置一次之後就不用再動了

@configuration
@enableswagger2
public
class
swaggerconfiguration
@bean
public apiinfo apiinfo()
}

特別要注意的是裡面配置了api檔案也就是controller包的路徑，不然生成的文件掃瞄不到介面

apis
(requesthandlerselectors.
basepackage
("com.yami.shop.api"
))

用@configuration註解該類，讓spring託管這個類，@bean標註方法等價於xml中配置bean

用@enableswagger2標識要開啟swagger2

在配置好之後，我們就可以對swagger進行使用,比如在areacontroller類中

@restcontroller
("/p/area"
)@api
(tags=
"省市區介面"
)public
class
areacontroller
}

@api(tags="省市區介面")定義標籤分組介面，在這個類下定義的所有介面將位於這個標籤之下

@apioperation()定義具體的介面標題資訊，notes可以為這個標籤新增注釋

@apiimplicitparam()對應的引數列表資訊，使用者告訴前端開發人員，這個介面需要傳遞什麼引數及引數的說明

如有多個引數需要說明，可使用@apiimplicitparams()下面可包含多個@apiimplicitparam()

@data
@tablename
("tz_area"
)public
class
area
implements
serializable

@apimodelproperty()利用這個註解可以告訴前端開發人員該欄位代表的含義

註解作用

@api

修飾整個類，描述controller的作用

@apioperation

描述乙個類的乙個方法，或者說乙個介面

@apiparam

單個引數描述

@apimodel

用物件來接收引數

@apiproperty

用物件接收引數時，描述物件的乙個字段

@apiresponse

http響應其中1個描述

@apiresponses

http響應整體描述

@apiignore

使用該註解忽略這個api

@apierror

發生錯誤返回的資訊

@apiimplicitparam

乙個請求引數

@apiimplicitparams

多個請求引數

我們仔細留意swagger文件，可以發現 swagger文件返回介面資料的url為：/v2/api-docs。這個url被springfox.documentation.swagger2.web.swagger2controlle#getdocumentation()關聯。通過jsonserializer.tojson(swagger)生成特定的json文件。

當我們使用pageparam這個分頁引數生成文件的時候，總是會返回泛型裡面的物件資訊，我們根據無論使用@apiparam(hidden = true)又或者是@jsonignore都無效，所以我們可以修改自己的jsonserializer生成的響應的json

自定義swagger 的序列化，去除分頁引數中的records值

public
class
springfoxjsonserializer
extends
jsonserializer
@override
public json tojson
(object toserialize)
swagger swagger =
(swagger)toserialize;
swagger.
getpaths()
.foreach
((key, path)
->}}
);return
super
.tojson
(swagger);}
}

新序列化的bean

@configuration public class springfoxjsonserializerconfig

}

Swagger文件使用

swagger文件註解使用

swagger介面文件的使用

使用swagger生成API文件

Swagger文件使用

swagger文件註解使用

swagger介面文件的使用

使用swagger生成API文件

相關推薦