springboot 结合 swagger2

spring boot 结合 swagger2

1. swagger 简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

2. 功能

1. 接口文档在线生成

2. 功能测试

感悟：现在的项目大部分都是前后端分离的，这样后端在写好后台接口后，在进行接口测试时，以往都是使用 postman 等工具来进行，这样很麻烦。swagger 很好的解决了这个问题。

3. 如何使用

1. Maven依赖

如果只引入 swagger 依赖，可能会报错，找不到某个类，所以还需要导入 google 的guava 包

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.6.1</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.6.1</version>
</dependency>
<dependency>
	<groupId>com.google.guava</groupId>
	<artifactId>guava</artifactId>
	<version>19.0</version>
</dependency>

2. 创建 SwaggerConfig 配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

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;

@Configuration
@EnableSwagger2
public class Swagger2Configure extends WebMvcConfigurerAdapter {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/");
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("xxx RESTful APIs").description("xxx api 接口文档").version("1.0").build();
    }
}

3. 编写 controller

@Api(value= "Test",description="测试 Test")
@RestController
@RequestMapping("/api")
public class Test {
	// 如果没有标注请求方式，页面默认显示所有的请求方法
	@ApiOperation(value = "测试 api", notes = "测试 api 接口")
	@RequestMapping(value = "/test",method = ResquestMethod.GET)
	@ApiImplicitParam(name = "username", value = "测试", required = true, paramType = "query")
	public void test(@RequestParam String username) {
		System.out.println("用户名" + username);
	}
}

4. 参数说明

注解	注解说明
@Api	用在类上，说明该类的作用
@ApiOperation	注解给 Api 方法说明
@ApiImplicitParams	用在方法上，包含一组参数说明
@ApiImplicitParam	用来注解来给方法入参增加说明
@ApiResponses	用于表示一组响应
@ApiResponse	用在@ApiResponses中，一般用于表达一个错误的响应信息
@ApiModel	描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty	描述一个model的属性

@ApiImplicitParam

在使用 swagger 时，页面中输入参数，后台总是获取不到，发现是 @ApiImplicitParam 注解用的方式不对

记录 @ApiImplicitParam 参数说明：

参数名称	作用	备注
paramType	指定参数放在哪个地方	header：请求参数放置于Request Header，使用@RequestHeader获取;query：请求参数放置于请求地址，使用@RequestParam获取;path：（用于restful接口）–>请求参数的获取：@PathVariable;body:(不常用);form（不常用）
name	参数名
dataType	参数类型
required	参数是否必须传
value	说明参数的意思
defaultValue	参数的默认值