Spring Boot集成springfox-swagger2構(gòu)建restful API的方法教程
前言
之前跟大家分享了Spring MVC集成springfox-swagger2構(gòu)建restful API，簡單寫了如何在springmvc中集成swagger2。這邊記錄下在springboot中如何集成swagger2。其實使用基本相同。
方法如下：
首先還是引用相關(guān)jar包。我使用的maven，在pom.xml中引用相關(guān)依賴(原來我使用的是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的配置類：
這個配置類和springmvc的寫法完全一致。為了區(qū)分我又重命名一個。
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();
}
}
在原來2.2.0的版本中使用new ApiInfo()的方法已經(jīng)過時，使用new ApiInfoBuilder()進行構(gòu)造，需要什么參數(shù)就添加什么參數(shù)。當(dāng)然也可以什么都添加。如：
private ApiInfo buildApiInfo(){
return new ApiInfoBuilder().build();
}
那么頁面顯示的效果如圖：
使用new ApiInfoBuilder().build()；
添加屬性：
點擊ApiInfoBuilder.Java的源碼可以看到相關(guān)方法使用。
第三步就是在自己的controller添加相關(guān)的注解：
原來使用在類上使用@controller，現(xiàn)在可以使用@RestController，然后方法的@ResponseBody就可以不用寫了，因為@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ù)說明
- @ApiModel()用于實體類
- @ApiModelProperty用于實體類屬性
更加詳細的含義可以參考官方說明wiki
下面會用代碼和示例圖說明。
第四部就是在啟動項目在瀏覽器上輸入url:
http://{ip}:{port}/swagger-ui.html#/
我在application.properties中設(shè)置的自己的端口號為9090(如果不設(shè)置，默認為8080)
server.port=9090
所以我的url是：http://localhost:9090/swagger-ui.html
如圖：
這里會把相應(yīng)包下的所有controller按類進行顯示。
我們看下其中一個類UserController.java,（請忽略業(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="用戶對象",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";
}
}
這里說明下，在使用對象作為參數(shù)時，可以在對象上添加相應(yīng)的注解，用戶頁面顯示。
如：
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="用戶對象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;
}
}
顯示的效果如圖：
看上圖紅框的部分，其中一個是json格式的點擊就可以獲取參數(shù)格式。
第二張中可以看到字段相應(yīng)的注釋和是否必填。
如果在字段上添加注釋@ApiModelProperty(required=true)就是必填（默認是false），相應(yīng)的頁面optional標(biāo)識也會消失，標(biāo)識這個字段必填。
點擊下面的try it out按鈕就可以進行調(diào)試。
在使用單個參數(shù)時，如上面代碼中的getUserInfo（）方法，對應(yīng)的效果圖如下：
這里如果是添加required=true， @ApiParam(required=true)則會在頁面上顯示required的標(biāo)識。同樣默認為false。
其他的使用方式可以自己動手試試。
總結(jié)
以上就是這篇文章的全部內(nèi)容了，希望本文的內(nèi)容對大家的學(xué)習(xí)或者工作能帶來一定的幫助，如有疑問大家可以留言交流，謝謝大家對腳本之家的支持。
相關(guān)文章
這篇文章主要介紹了Java實現(xiàn)的程序員老黃歷實例，小編覺得挺不錯的，現(xiàn)在分享給大家，也給大家做個參考。一起跟隨小編過來看看吧2018-05-05
這篇文章主要介紹了Java之Class.forName()用法案例詳解,本篇文章通過簡要的案例,講解了該項技術(shù)的了解與使用,以下就是詳細內(nèi)容,需要的朋友可以參考下2021-09-09
這篇文章主要介紹了淺談MyBatis通用Mapper實現(xiàn)原理，本文會先介紹通用 Mapper 的簡單原理，然后使用最簡單的代碼來實現(xiàn)這個過程。感興趣的小伙伴們可以參考一下2018-10-10
深入理解SpringMVC中央調(diào)度器DispatcherServlet
這篇文章主要介紹了SpringMVC核心之中央調(diào)度器DispatcherServlet的相關(guān)知識,包括SpringMVC請求處理過程及SrpingMVC容器和spring?IOC容器關(guān)系，需要的朋友可以參考下2022-05-05
這篇文章主要介紹了Java函數(shù)式編程(十一)：遍歷目錄,本文是系列文章的第11篇,其它文章請參閱本文底部的相關(guān)文章,需要的朋友可以參考下2014-09-09
Picocli 是一個強大、易用且功能豐富的 Java 庫,用于開發(fā)命令行工具,本文我們就來為大家介紹一下Java如何利用Picocli進行命令行簡化功能的吧2025-03-03
本篇文章主要是對通過url方式傳遞中文亂碼的解決方法進行了介紹，需要的朋友可以過來參考下，希望對大家有所幫助2013-12-12
這篇文章主要為大家詳細介紹了用java方法實現(xiàn)簡易ATM功能，文中示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下2021-04-04
springboot項目攔截前端請求中的特殊字符串(解決方案)
springboot項目中,需要對前端請求數(shù)據(jù)進行過濾,攔截特殊字符,本文通過實例代碼給大家分享完美解決方案,感興趣的朋友一起看看吧2023-10-10
Spring是一個廣泛應(yīng)用的框架，SpringAOP則是Spring提供的一個標(biāo)準(zhǔn)易用的aop框架，依托Spring的IOC容器，提供了極強的AOP擴展增強能力，對項目開發(fā)提供了極大地便利2022-11-11