依賴
|
1
2
3
4
5
6
7
8
9
10
|
<dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger2</artifactid> <version>2.7.0</version></dependency><dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger-ui</artifactid> <version>2.7.0</version></dependency> |
配置類
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
|
import org.springframework.context.annotation.bean;import org.springframework.context.annotation.configuration;import springfox.documentation.builders.apiinfobuilder;import springfox.documentation.builders.pathselectors;import springfox.documentation.builders.requesthandlerselectors;import springfox.documentation.service.apiinfo;import springfox.documentation.service.contact;import springfox.documentation.spi.documentationtype;import springfox.documentation.spring.web.plugins.docket;/** * swagger的配置類 * @author 陳加兵 * */@configurationpublic class swaggerconfig{ /** * 創(chuàng)建用戶api文檔 * @return */ @bean public docket createrestuserapi(){ return new docket(documentationtype.swagger_2) .groupname("user") .apiinfo(apiinfo()) //api的信息 .select() .apis(requesthandlerselectors .basepackage("cn.tedu.mycat.controller")) //添加包掃描 .paths(pathselectors.any()).build(); } /** * 創(chuàng)建api信息 */ private apiinfo apiinfo(){ return new apiinfobuilder() .title("api文檔的標(biāo)題") //標(biāo)題 .description("api文檔的描述") //描述 .contact( //添加開發(fā)者的一些信息 new contact("愛撒謊的男孩", "https://chenjiabing666.github.io", "18796327106@163.com")).version("1.0").build(); }} |
啟動類
在springboot的啟動類上添加一個注解即可配置成功： @enableswagger2
訪問api的路徑
http://ip/projectname/swagger-ui.html
注解說明
@api
- 標(biāo)注在類上，用來對這個類進(jìn)行說明的
- 如果想要生成文檔，必須在類或者接口上標(biāo)注
- 屬性如下：
| 屬性名稱 | 備注 | 默認(rèn)值 |
|---|---|---|
| value | url的路徑值 | |
| tags | 如果設(shè)置這個值、value的值會被覆蓋 | |
| description | 對api資源的描述 | |
| basepath | 基本路徑可以不配置 | |
| position | 如果配置多個api 想改變顯示的順序位置 | |
| produces | for example, “application/json, application/xml” | |
| consumes | for example, “application/json, application/xml” | |
| protocols | possible values: http, https, ws, wss. | |
| authorizations | 高級特性認(rèn)證時配置 | |
| hidden | 配置為true 將在文檔中隱藏 |
@apioperation
- 用在api方法上，對該api做注釋，說明api的作用
- 不需要多講，看源碼，使用默認(rèn)的value屬性即可，說明該方法的作用
- 屬性如下：
| value | url的路徑值 | |
|---|---|---|
| tags | 如果設(shè)置這個值、value的值會被覆蓋 | |
| notes | 對api資源的描述 | |
| response | 返回的對象，在文檔中點擊model可以獲取該配置的內(nèi)容 | |
| responsecontainer | 這些對象是有效的 “list”, “set” or “map”.，其他無效 | |
| responsereference | 可以不配置 | |
| httpmethod | 可以接受 “get”, “head”, “post”, “put”, “delete”, “options” and “patch” | |
| position | 如果配置多個api 想改變顯示的順序位置 | |
| produces | 同 api中的定義 | |
| consumes | 同 api中的定義 | |
| protocols | 同 api中的定義 | |
| authorizations | 同 api中的定義 | |
| hidden | 是否隱藏，true 或者false ，這個可以隱藏后臺接口 | |
| code | http的狀態(tài)碼 默認(rèn) 200 | |
| extensions | 擴(kuò)展屬性 |
@apiimplicitparams
- 用來包含api的一組參數(shù)注解，可以簡單的理解為參數(shù)注解的集合聲明
- 很重要，這個注解其中包含接口入?yún)⒌脑敿?xì)說明
- 內(nèi)容是集合
@apiimplicitparam
用在 @apiimplicitparams 注解中，也可以單獨使用，說明一個請求參數(shù)的各個方面
詳細(xì)的屬性使用說明如下：
- name ：屬性的字段名稱，相當(dāng)于form表單中的name，這個就是入?yún)⒌淖侄?/li>
- datatype ：參數(shù)的類型，標(biāo)識，字符串
- value ：該參數(shù)的描述
- required ：是否必填，布爾值
- defaultvalue ：缺省值，會在文檔中缺省填入，這樣更方面造數(shù)據(jù)，不需要調(diào)用接口的去填值了
-
paramtype ：指定參數(shù)的入?yún)?shù)方式（也就是請求參數(shù)的位置），其中有四種常用的，如下：
- query
- path
- body
- form
paramtype屬性的詳細(xì)說明
- query ：必須要和入?yún)⒌淖侄我粯樱部梢允褂?@requestparam() 指定
- path ：用于restful的風(fēng)格的url，請求的參數(shù)寫在路徑上，如下：
|
1
2
3
4
5
6
7
8
|
@apioperation(value="根據(jù)用戶id獲取用戶信息",response=user.class,hidden=false) @apiimplicitparams({ @apiimplicitparam(paramtype = "path", name = "id", datatype="integer", required = false, value = "用戶的id", defaultvalue = "1") }) @getmapping("/user/get/{id}") public object getuser(@pathvariable("id")integer id){ return new user(id, "陳加兵"); } |
-
body：以流的形式提交 僅支持post
form：以表單的形式提交
以上就是本文的全部內(nèi)容，希望對大家的學(xué)習(xí)有所幫助，也希望大家多多支持服務(wù)器之家。
原文鏈接：https://chenjiabing666.github.io/2018/10/21/SpringBoot整合Swagger/
