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文档