程式師世界 >> 編程語言 >> JAVA編程 >> 關於JAVA >> Spring Boot集成springfox-swagger2構建restful API的方法教程

Spring Boot集成springfox-swagger2構建restful API的方法教程

編輯：關於JAVA

前言

之前跟大家分享了Spring MVC集成springfox-swagger2構建restful API，簡單寫了如何在springmvc中集成swagger2。這邊記錄下在springboot中如何集成swagger2。其實使用基本相同。

方法如下：

首先還是引用相關jar包。我使用的maven，在pom.xml中引用相關依賴(原來我使用的是2.2.0的，現在使用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>

第二步就是創建swagger的配置類：

這個配置類和springmvc的寫法完全一致。為了區分我又重命名一個。

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大標題")
     .description("springboot swagger2")
     .termsOfServiceUrl("http://blog.csdn.net/u014231523網址鏈接")
     .contact(new Contact("diaoxingguo", "http://blog.csdn.net/u014231523", "[email protected]"))
     .build();

 }

}

在原來2.2.0的版本中使用new ApiInfo()的方法已經過時，使用new ApiInfoBuilder()進行構造，需要什麼參數就添加什麼參數。當然也可以什麼都添加。如：

private ApiInfo buildApiInfo(){
 return new ApiInfoBuilder().build();
}

那麼頁面顯示的效果如圖：

使用new ApiInfoBuilder().build()；

添加屬性：

點擊ApiInfoBuilder.Java的源碼可以看到相關方法使用。

第三步就是在自己的controller添加相關的注解：

原來使用在類上使用@controller，現在可以使用@RestController，然後方法的@ResponseBody就可以不用寫了，因為@RestController的注解接口上已經添加了，要求版本在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()用於參數說明

- @ApiModel()用於實體類

- @ApiModelProperty用於實體類屬性

更加詳細的含義可以參考官方說明wiki

下面會用代碼和示例圖說明。

第四部就是在啟動項目在浏覽器上輸入url:

http://{ip}:{port}/swagger-ui.html#/

我在application.properties中設置的自己的端口號為9090(如果不設置，默認為8080)

server.port=9090

所以我的url是：http://localhost:9090/swagger-ui.html

如圖：

這裡會把相應包下的所有controller按類進行顯示。

我們看下其中一個類UserController.java,（請忽略業務邏輯，只看注解）

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";
 }
}

這裡說明下，在使用對象作為參數時，可以在對象上添加相應的注解，用戶頁面顯示。

如：

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="狀態",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;
 }


}

顯示的效果如圖：