前言
之前跟大家分享了Spring MVC集成springfox-swagger2構(gòu)建restful API，簡單寫了如何在springmvc中集成swagger2。這邊記錄下在springboot中如何集成swagger2。其實(shí)使用基本相同。
方法如下：
首先還是引用相關(guān)jar包。我使用的maven，在pom.xml中引用相關(guān)依賴(原來我使用的是2.2.0的，現(xiàn)在使用2.4.0的)：
|
1
2
3
4
5
6
7
8
9
10
|
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.4.0</version></dependency><dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.4.0</version></dependency> |
第二步就是創(chuàng)建swagger的配置類：
這個(gè)配置類和springmvc的寫法完全一致。為了區(qū)分我又重命名一個(gè)。
|
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
|
package com.xingguo.springboot;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;import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration@EnableSwagger2public class Swagger2Configuration { @Bean public Docket buildDocket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(buildApiInf()) .select() .apis(RequestHandlerSelectors.basePackage("com.xingguo.springboot.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo buildApiInf(){ return new ApiInfoBuilder() .title("xingguo大標(biāo)題") .description("springboot swagger2") .termsOfServiceUrl("http://blog.csdn.net/u014231523網(wǎng)址鏈接") .contact(new Contact("diaoxingguo", "http://blog.csdn.net/u014231523", "diaoxingguo@163.com")) .build(); }} |
在原來2.2.0的版本中使用new ApiInfo()的方法已經(jīng)過時(shí)，使用new ApiInfoBuilder()進(jìn)行構(gòu)造，需要什么參數(shù)就添加什么參數(shù)。當(dāng)然也可以什么都添加。如：
|
1
2
3
|
private ApiInfo buildApiInfo(){ return new ApiInfoBuilder().build();} |
那么頁面顯示的效果如圖：
使用new ApiInfoBuilder().build()；
添加屬性：
點(diǎn)擊ApiInfoBuilder.Java的源碼可以看到相關(guān)方法使用。
第三步就是在自己的controller添加相關(guān)的注解：
原來使用在類上使用@controller，現(xiàn)在可以使用@RestController，然后方法的@ResponseBody就可以不用寫了，因?yàn)?code>@RestController的注解接口上已經(jīng)添加了，要求版本在4.0.1之后。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
@Target(ElementType.TYPE)@Retention(RetentionPolicy.RUNTIME)@Documented@Controller@ResponseBodypublic @interface RestController { /** * The value may indicate a suggestion for a logical component name, * to be turned into a Spring bean in case of an autodetected component. * @return the suggested component name, if any * @since 4.0.1 */ String value() default "";} |
常用的注解如下：
- @Api()用于類名
- @ApiOperation()用于方法名
- @ApiParam()用于參數(shù)說明
- @ApiModel()用于實(shí)體類
- @ApiModelProperty用于實(shí)體類屬性
更加詳細(xì)的含義可以參考官方說明wiki
下面會(huì)用代碼和示例圖說明。
第四部就是在啟動(dòng)項(xiàng)目在瀏覽器上輸入url:
http://{ip}:{port}/swagger-ui.html#/
我在application.properties中設(shè)置的自己的端口號(hào)為9090(如果不設(shè)置，默認(rèn)為8080)
|
1
|
server.port=9090 |
所以我的url是：http://localhost:9090/swagger-ui.html
如圖：
這里會(huì)把相應(yīng)包下的所有controller按類進(jìn)行顯示。
我們看下其中一個(gè)類UserController.java,（請(qǐng)忽略業(yè)務(wù)邏輯，只看注解）
|
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
47
48
49
|
package com.xingguo.springboot.controller;import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;import io.swagger.annotations.ApiParam;import javax.annotation.Resource;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.PostMapping;import org.springframework.web.bind.annotation.RequestBody;import org.springframework.web.bind.annotation.ResponseBody;import org.springframework.web.bind.annotation.RestController;import com.xingguo.springboot.model.User;import com.xingguo.springboot.service.UserService;/** * Created by diaoxingguo on 2016/10/24. */@Api(value="用戶controller",description="用戶操作",tags={"用戶操作接口"})@RestControllerpublic class UserController { @Resource private UserService userService; @ApiOperation("獲取用戶信息") @GetMapping("/getUserInfo") public User getUserInfo(@ApiParam(name="id",value="用戶id",required=true) Long id,@ApiParam(name="username",value="用戶名") String username) { User user = userService.getUserInfo(); return user; } @ApiOperation("更改用戶信息") @PostMapping("/updateUserInfo") public int updateUserInfo(@RequestBody @ApiParam(name="用戶對(duì)象",value="傳入json格式",required=true) User user){ int num = userService.updateUserInfo(user); return num; } @ApiOperation("添加用戶信息") @PostMapping("/saveUser") public String saveUser(@RequestBody @ApiParam(name="user",value="json fromat",required=true) User user) { userService.saveUser(user); return "success"; }} |
這里說明下，在使用對(duì)象作為參數(shù)時(shí)，可以在對(duì)象上添加相應(yīng)的注解，用戶頁面顯示。
如：
|
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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
|
package com.xingguo.springboot.model;import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;import java.util.List;/** * Created by diaoxingguo on 2016/10/24. */@ApiModel(description="用戶對(duì)象user")public class User { @ApiModelProperty(value="用戶名",name="username") private String username; @ApiModelProperty(value="狀態(tài)",name="state",required=true) private Integer state; private String password; private String nickName; private Integer isDeleted; private String[] ids; private List<String> idList; public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } public Integer getState() { return state; } public void setState(Integer state) { this.state = state; } public String getPassword() { return password; } public void setPassword(String password) { this.password = password; } public String[] getIds() { return ids; } public void setIds(String[] ids) { this.ids = ids; } public List<String> getIdList() { return idList; } public void setIdList(List<String> idList) { this.idList = idList; } public String getNickName() { return nickName; } public void setNickName(String nickName) { this.nickName = nickName; } public Integer getIsDeleted() { return isDeleted; } public void setIsDeleted(Integer isDeleted) { this.isDeleted = isDeleted; }} |
顯示的效果如圖：
看上圖紅框的部分，其中一個(gè)是json格式的點(diǎn)擊就可以獲取參數(shù)格式。
第二張中可以看到字段相應(yīng)的注釋和是否必填。
如果在字段上添加注釋@ApiModelProperty(required=true)就是必填（默認(rèn)是false），相應(yīng)的頁面optional標(biāo)識(shí)也會(huì)消失，標(biāo)識(shí)這個(gè)字段必填。
點(diǎn)擊下面的try it out按鈕就可以進(jìn)行調(diào)試。
在使用單個(gè)參數(shù)時(shí)，如上面代碼中的getUserInfo（）方法，對(duì)應(yīng)的效果圖如下：
這里如果是添加required=true， @ApiParam(required=true)則會(huì)在頁面上顯示required的標(biāo)識(shí)。同樣默認(rèn)為false。
其他的使用方式可以自己動(dòng)手試試。
總結(jié)
以上就是這篇文章的全部內(nèi)容了，希望本文的內(nèi)容對(duì)大家的學(xué)習(xí)或者工作能帶來一定的幫助，如有疑問大家可以留言交流，謝謝大家對(duì)服務(wù)器之家的支持。
原文鏈接：http://blog.csdn.net/u014231523/article/details/54562695
