SpringBoot整合Swagger

第一步：添加相关依赖 

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

<properties>
    <swagger2.version>2.7.0</swagger2.version>
</properties>

<dependencies>
    <!--springBoot 相关依赖-->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!--swagger2 相关依赖-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${swagger2.version}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger2.version}</version>
    </dependency>

</dependencies>

创建SrpingBoot启动类

/**
 * Springboot+Swagger整合启动类
 * 
 * @author Y.yang
 * @date 2019/3/12
 */
@SpringBootApplication
public class SwaggerApplication {

	public static void main(String[] args) {
		SpringApplication.run(SwaggerApplication.class, args);
	}
}

第二步：配置Swagger2

注意添加 @Configuration  EnableSwagger2注解

/**
 * Swagger2 接口Api文档 配置文件
 * 
 * @author Y.yang
 * @date 2019/3/12
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 初始化创建Swagger Api
     */
    @Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				// 详细信息定制
				.apiInfo(apiInfo())
				.select()
				// 指定当前包路径
				.apis(RequestHandlerSelectors.basePackage("com.fame.controller"))
				// 扫描所有 .apis(RequestHandlerSelectors.any())
				.paths(PathSelectors.any())
				.build();
	}

	/**
	 * 添加摘要信息
	 */
	private ApiInfo apiInfo() {
		// 用ApiInfoBuilder进行定制
		return new ApiInfoBuilder()
				.title("标题：springBoot-Swagger2整合学习")
				.description("描述：文档构建器")
				.contact(new Contact("Fame-springBoot-Swagger2", null, null))
				.version("版本号: 1.0")
				.build();
	}
}

springfox为我们提供了一个Docket（摘要的意思）类，我们需要把它做成一个Bean注入到spring中，
显然，我们需要一个配置文件，并通过一种方式（显然它会是一个注解）告诉程序，这是一个Swagger配置文件。

springfox允许我们将信息组合成一个ApiInfo的类，作为构造参数传给Docket（当然也可以不构造这个类，而直接使用null，但是你的这个API就太low了）。

 第三步：创建测试实例

/**
 * Swagger接口测试
 * 
 * @author Y.yang
 * @date 2019/3/12
 */
@RestController
public class UserController {

    @GetMapping("/get")
    public String get(){
        return "Hello Swagger2";
    }
}

第四步：输入SwaggerUI地址

http://localhost:8080/swagger-ui.html

Swagger2基本使用-常用注解

接口/方法常用注解

package com.example.demo.controller;

import com.example.demo.bean.UserDao;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;

@Controller
@RequestMapping("/user")
@Api(value = "用户信息管理")
public class UserController {
    UserDao userDao;

    @RequestMapping(method = RequestMethod.POST, value = "/userById")
    @ApiOperation(value = "获取用户信息", notes = "通过用户ID获取用户信息")
    public Object findById(@ApiParam(value = "用户ID", required = true) int id) {
        return userDao.findById(id);
    }

    @RequestMapping(value = "/userByName", method = RequestMethod.POST)
    @ApiOperation(value = "获取用户信息", notes = "通过用户姓名获取用户信息")
    @ApiImplicitParam(name = "names", value = "用户姓名", required = true, dataType = "String", paramType = "query")
    @ResponseBody
    public Object findByName(String names) {
        return "ok" + names;
    }

    @RequestMapping("/age")
    @ResponseBody
    public Object age(String age) {
        return "ok" + age;
    }
}

@Api: 描述类/接口的主要用途

用于类；表示标识这个类是swagger的资源
tags–表示说明
value–也是说明，不会显示在接口文档上，可以使用tags替代

但是tags如果有多个值，会生成多个list

@Api(value = "用户信息", tags = { "用户信息" })

@ApiOperation: 描述方法用途

@ApiOperation(value = "用户信息分页查询")

@ApiImplicitParam: 描述方法的参数

@ApiImplicitParams: 描述方法的参数(Multi-Params)

@ApiImplicitParams({
	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer"),
	@ApiImplicitParam(name = "file", value = "文件导入", dataType = "MultipartFile")
})

实体类常用注解

/**
 * 用户信息 数据传输对象 Dto（Data Transfer Object）
 * 
 * @author Y.yang
 * @date 2019/3/29
 */
@ApiModel(description = "用户信息请求对象")
@Data
public class User implements Serializable {

	private static final long serialVersionUID = -6986638131456347054L;

	@ApiModelProperty(value = "姓名")
	private String username;

	@ApiModelProperty(value = "性别")
	private String sex;

	@ApiModelProperty(value = "年龄")
	private Integer age;

}

@ApiModel:描述实体类（Dto、Vo、Do等）

@ApiModel(description = "用户信息请求对象")

@ApiModelProperty：描述实体类的字段

@ApiModelProperty(value = "姓名")

在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：

 @Api：修饰整个类，描述Controller的作用 
 @ApiOperation：描述一个类的一个方法，或者说一个接口
 @ApiParam：单个参数描述 
 @ApiModel：用对象来接收参数
 @ApiModelProperty：用对象接收参数时，描述对象的一个字段
 @ApiResponse：HTTP响应其中1个描述
 @ApiResponses：HTTP响应整体描述
 @ApiIgnore：使用该注解忽略这个API
 @ApiError ：发生错误返回的信息
 @ApiImplicitParam：一个请求参数
 @ApiImplicitParams：多个请求参数
 @ApiImplicitParam属性