java Spring Boot 整合使用Swagger2構建強大的RESTful API文檔

項目結構圖：

1、在pom.xml中加入Swagger2的依賴

                <!-- 加入Swagger2的依賴 -->
                <dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger2</artifactId>
	    	<version>2.9.2</version>
		</dependency>
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger-ui</artifactId>
		    <version>2.9.2</version>
		</dependency>
		<!-- 加入Swagger2的依賴 -->

2、在Application.java同級創建Swagger2的配置類Swagger2。

package com.sky;

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;

//swagger2的配置文件，在項目的啓動類的同級文件建立
@Configuration
@EnableSwagger2 //重要
public class Swagger2 {
	//swagger2的配置文件，這裏可以配置swagger2的一些基本的內容，比如掃描的包等等
	@Bean
	public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //爲當前包路徑
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller"))
                .paths(PathSelectors.any())
                .build();
	}

	//構建 api文檔的詳細信息函數,注意這裏的註解引用的是哪個
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				//頁面標題
                .title("Spring Boot 測試使用 Swagger2 構建RESTful API")
                //創建人
                .contact(new Contact("GodSky", "http://www.baidu.com", ""))
                //版本號
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
	}
}

 

如上代碼所示，通過@Configuration註解，讓Spring來加載該類配置。再通過@EnableSwagger2註解來啓用Swagger2。

再通過createRestApi函數創建Docket的Bean之後，apiInfo()用來創建該Api的基本信息（這些基本信息會展現在文檔頁面中）。select()函數返回一個ApiSelectorBuilder實例用來控制哪些接口暴露給Swagger來展現，本例採用指定掃描的包路徑來定義，Swagger會掃描該包下所有Controller定義的API，併產生文檔內容（除了被@ApiIgnore指定的請求）。

3、添加文檔內容

在完成了上述配置後，其實已經可以生產文檔內容，但是這樣的文檔主要針對請求本身，而描述主要來源於函數等命名產生，對用戶並不友好，我們通常需要自己增加一些說明來豐富文檔內容。如下所示，我們通過@ApiOperation註解來給API增加說明、通過@ApiImplicitParams、@ApiImplicitParam註解來給參數增加說明。

package com.sky.controller;

import java.util.List;

import org.apache.log4j.Logger;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.sky.entity.UserList;
import com.sky.service.UserListService;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

@RequestMapping("ssm")
@RestController
@Api(value="swagger2Controller Test API", tags="SSMTestAPI")
public class UserController {
	private static final Logger log = Logger.getLogger(UserController.class);// 日誌文件
	
	@Autowired 
	private UserListService userListService;
	
	@ApiOperation(value="查詢userList", notes="查詢所有user")
	@RequestMapping(value="userlistall", method=RequestMethod.POST) //使用POST。GET的話http://127.0.0.1:8080/swagger-ui.html會產生很多菜單
	public List<UserList> userLists(){
		List<UserList> list=this.userListService.selectUserAll();
		log.info(list);
		return list;
	}
	
	
	//使用spring boot運行時，路徑不需要加工程名
	@ApiOperation(value="根據id查詢user", notes="根據id查詢user")
	@ApiImplicitParam(name="userid", value="必填", dataType="Integer", paramType="query") //required=true不知道爲啥不行，加上就不能測試
	@RequestMapping(value="userlist", method=RequestMethod.POST) //使用POST。GET的話http://127.0.0.1:8080/swagger-ui.html會產生很多菜單
	public UserList selectByPrimaryKey(Integer userid){
		UserList userList=this.userListService.selectByPrimaryKey(userid);
		log.info(userList);
		return userList;
	}
}

完成上述代碼添加上，啓動Spring Boot程序，訪問：http://localhost:8080/swagger-ui.html 。就能看到前文所展示的RESTful API的頁面。

 注：

1、Controller中的方法儘量使用POST，使用GET的話http://127.0.0.1:8080/swagger-ui.html會產生很多菜單。

2、使用spring boot運行時，路徑不需要加工程名。

3、可詳細查看@ApiImplicitParam文檔