SpringBoot集成Swagger2

Swagger2是一款生成API文档工具

一、环境搭建

开发工具：Spring Tool Suite v_3.9.3（简称STS）

依赖包管理（pom.xml）：

测试 SpringBoot 1.5.3 版本需要 swagger2 1.8.0 版本，SpringBoot 1.4.2 版本 swagger2 1.6.1 版本可用

<parent>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-parent</artifactId>
	<version>1.5.3.RELEASE</version>
</parent>

<dependencies>
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.8.0</version>
	</dependency>
	
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.8.0</version>
	</dependency>
</dependencies>

配置类

package com.info.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2配置类：最好和SpringBoot启动类在同一级（Application）
 */
@Configuration
@EnableSwagger2 // 启动Swagger2
public class Swagger2Config {

	/**
	 * 创建Docker对象 
	 * Docker apiInfo()：用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
	 * 
	 * ApiSelectorBuilder select()：设置哪些接口暴露给Swagger展示 
	 * ApiSelectorBuilder apis()：要展示的API apis() 
	 * 		RequestHandlerSelectors.any() 任何路径
	 * 		RequestHandlerSelectors.basePackage("com.info.*")  包位置
	 * 		RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)  类位置
	 * ApiSelectorBuilder paths()：要展示的路径 
	 * 		PathSelectors.any()：任何路径都可以 
	 * Docker build()：创建Docker对象
	 */
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();
	}

	/**
	 * 自定义该API工具展示信息，标题、描述、更新的地址、作者信息、版本等
	 * 
	 * ApiInfoBuilder title(String str): 设置标题
	 * ApiInfoBuilder description(String str): 描述
	 * ApiInfoBuilder termsOfServiceUrl(String str): 更新地址
	 * ApiInfoBuilder contact(String str): 作者信息
	 * ApiInfoBuilder version(String str): 版本
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("标题").build();
	}

}

测试：登录地址 http://localhost:8080/swagger-ui.html

三、Swagger2使用

Swagger2使用的时候需要在相应的类上加上注解，具体如下：

@Api      类级别注解，配置类的标题信息

tags：标题
description：信息
hidden = true：是否可以展开显示

@Api("权限接口") // 接口的标题信息
@RestController
public class Controller { }

@ApiOperation      配置接口的标题信息，作用在方法上

value：接口说明
httpMethod：接口请求方式
response：接口返回参数类型
notes：接口发布说明

@ApiOperation(value="查询日志", notes="查询", httpMethod="POST")
public void querAllLogs() { }

@ApiParam      方法参数信息描述，作用在方法上或参数上

required：是否必须参数
name：参数名称
value：参数具体描述
dataType：参数类型

@ApiImplicitParam(name="id", value="用户id", required=true, dataType="int")

可以简化使用：

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

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

@Api("权限接口") // 接口的标题信息
@RestController
public class Controller {

	@ApiOperation(value = "获取指定用户的角色")
	@RequestMapping(value = "/getRolesByUserCode", method = RequestMethod.GET)
	public void find(@ApiParam(value = "用户名称") @RequestParam String userCode) {

	}
}

注：前台数据来源位置

参数在请求体中：@RequestBody POST
参数在在路径中：@PathVariable @RequestMapping(value = “/index/{userCode}”, method = RequestMethod.GET)
参数在在路径中：@RequestParam GET http://localhost:8080/index?userCode=Admin