Spring Boot集成springfox-swagger2構(gòu)建restful API的方法教程
前言
之前跟大家分享了Spring MVC集成springfox-swagger2構(gòu)建restful API,簡(jiǎn)單寫了如何在springmvc中集成swagger2。這邊記錄下在springboot中如何集成swagger2。其實(shí)使用基本相同。
方法如下:
首先還是引用相關(guān)jar包。我使用的maven,在pom.xml中引用相關(guān)依賴(原來(lái)我使用的是2.2.0的,現(xiàn)在使用2.4.0的):
<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è)。
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 @EnableSwagger2 public 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(); } }
在原來(lái)2.2.0的版本中使用new ApiInfo()
的方法已經(jīng)過時(shí),使用new ApiInfoBuilder()
進(jìn)行構(gòu)造,需要什么參數(shù)就添加什么參數(shù)。當(dāng)然也可以什么都添加。如:
private ApiInfo buildApiInfo(){ return new ApiInfoBuilder().build(); }
那么頁(yè)面顯示的效果如圖:
使用new ApiInfoBuilder().build();
添加屬性:
點(diǎn)擊ApiInfoBuilder.Java
的源碼可以看到相關(guān)方法使用。
第三步就是在自己的controller添加相關(guān)的注解:
原來(lái)使用在類上使用@controller
,現(xiàn)在可以使用@RestController
,然后方法的@ResponseBody
就可以不用寫了,因?yàn)?code>@RestController的注解接口上已經(jīng)添加了,要求版本在4.0.1之后。
@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) @Documented @Controller @ResponseBody public @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ù)說(shuō)明
- @ApiModel()
用于實(shí)體類
- @ApiModelPropert
y用于實(shí)體類屬性
更加詳細(xì)的含義可以參考官方說(shuō)明wiki
下面會(huì)用代碼和示例圖說(shuō)明。
第四部就是在啟動(dòng)項(xiàng)目在瀏覽器上輸入url:
http://{ip}:{port}/swagger-ui.html#/
我在application.properties
中設(shè)置的自己的端口號(hào)為9090(如果不設(shè)置,默認(rèn)為8080)
server.port=9090
所以我的url是:http://localhost:9090/swagger-ui.html
如圖:
這里會(huì)把相應(yīng)包下的所有controller按類進(jìn)行顯示。
我們看下其中一個(gè)類UserController.java
,(請(qǐng)忽略業(yè)務(wù)邏輯,只看注解)
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={"用戶操作接口"}) @RestController public 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"; } }
這里說(shuō)明下,在使用對(duì)象作為參數(shù)時(shí),可以在對(duì)象上添加相應(yīng)的注解,用戶頁(yè)面顯示。
如:
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)的頁(yè)面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ì)在頁(yè)面上顯示required的標(biāo)識(shí)。同樣默認(rèn)為false。
其他的使用方式可以自己動(dòng)手試試。
總結(jié)
以上就是這篇文章的全部?jī)?nèi)容了,希望本文的內(nèi)容對(duì)大家的學(xué)習(xí)或者工作能帶來(lái)一定的幫助,如有疑問大家可以留言交流,謝謝大家對(duì)腳本之家的支持。
相關(guān)文章
Docker?DockerFile部署java?jar項(xiàng)目包及Mysql和Redis的詳細(xì)過程
Dockerfile是一種用于構(gòu)建Docker鏡像的文件格式,可以通過Dockerfile部署Java項(xiàng)目,這篇文章主要給大家介紹了關(guān)于Docker?DockerFile部署java?jar項(xiàng)目包及Mysql和Redis的詳細(xì)過程,需要的朋友可以參考下2023-12-12java request.getHeader("user-agent")獲取瀏覽器信息的方法
這篇文章主要介紹了java request.getHeader("user-agent")獲取瀏覽器信息的方法,文中通過示例代碼介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧2019-03-03java使用Process調(diào)用exe程序及Process.waitFor()死鎖問題解決
在編寫Java程序時(shí),有時(shí)候我們需要調(diào)用其他的諸如exe,shell這樣的程序或腳本,下面這篇文章主要給大家介紹了關(guān)于java使用Process調(diào)用exe程序及Process.waitFor()死鎖問題解決的相關(guān)資料,需要的朋友可以參考下2022-12-12intellij idea如何配置網(wǎng)絡(luò)代理
intellij idea所在的這臺(tái)電腦本身上不了網(wǎng),要通過代理上網(wǎng),那么intellij idea怎么設(shè)置代理上網(wǎng)呢?今天通過本文給大家分享intellij idea如何配置網(wǎng)絡(luò)代理,感興趣的朋友一起看看吧2023-10-10Java8新特性Stream流中anyMatch和allMatch和noneMatch的區(qū)別解析
這篇文章主要介紹了Java8新特性Stream流中anyMatch和allMatch和noneMatch的區(qū)別解析,本文給大家介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值,需要的朋友參考下吧2024-01-01實(shí)例講解Java并發(fā)編程之ThreadLocal類
這篇文章主要介紹了實(shí)例講解Java并發(fā)編程之ThreadLocal類,本文給出了模擬ThreadLocal、實(shí)用ThreadLocal等代碼實(shí)例,需要的朋友可以參考下2015-04-04