SpringBoot集成Swagger

引入jar包

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

编写配置类

import java.util.ArrayList;
import java.util.List;

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.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author wlddh
 *
 */
@Configuration
@EnableSwagger2
public class Swagger2Config extends WebMvcConfigurerAdapter {
	/**
	 * 这个地方要重新注入一下资源文件，不然不会注入资源的，也没有注入requestHandlerMappping,相当于xml配置的
	 * <!--swagger资源配置-->
	 * <mvc:resources location="classpath:/META-INF/resources/" mapping=
	 * "swagger-ui.html"/>
	 * <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping=
	 * "/webjars/**"/> 不知道为什么，这也是spring boot的一个缺点（菜鸟觉得的）
	 * 
	 * @param registry
	 */
	@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
		registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
		registry.addResourceHandler("/webjars*").addResourceLocations("classpath:/META-INF/resources/webjars/");
	}

	// 可以注入多个doket，也就是多个版本的api，可以在看到有三个版本groupName不能是重复的，v1和v2是ant风格匹配，配置文件
	@Bean
	public Docket api() {
		// 可以添加多个header或参数
//		ParameterBuilder aParameterBuilder = new ParameterBuilder();
//		aParameterBuilder.parameterType("header") // 参数类型支持header, cookie, body, query etc
//				.name("token") // 参数名
//				.defaultValue("token") // 默认值
//				.description("header中token字段测试").modelRef(new ModelRef("string"))// 指定参数值的类型
//				.required(false).build(); // 非必需，这里是全局配置，然而在登陆的时候是不用验证的
//		List<Parameter> aParameters = new ArrayList<Parameter>();
//		aParameters.add(aParameterBuilder.build());
		return new Docket(DocumentationType.SWAGGER_2).groupName("v1").select().apis(RequestHandlerSelectors.basePackage("com.hsoft.stock.server.api"))
				.paths(PathSelectors.any()).build().apiInfo(apiInfo1());
//				.globalOperationParameters(aParameters);
	}

	private ApiInfo apiInfo1() {
		return new ApiInfoBuilder().title("exampleApi 0.01").termsOfServiceUrl("")
				.contact(new Contact("wlddhj", "http:///wlddhj", "wlddhj@")).version("v0.01")
				.build();
	}
}

文档注解示例

注解写在接口方法上面

@ApiOperation(value = "查询所有可用", notes = "查询所有可用牌号")
@ApiResponses({ @ApiResponse(code = 400, message = "请求参数没填好"), @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对") })
@ApiImplicitParam(name = "searchVo", value = "查询Vo", required = true, dataType = "BsBrandSearchVo")

常用注解说明

1. @Api：用在类上，说明该类的作用
2. @ApiOperation：用在方法上，说明方法的作用
3. @ApiImplicitParams：用在方法上包含一组参数说明
4. @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

• paramType：参数放在哪个地方
• header–>请求参数的获取：@RequestHeader
• query–>请求参数的获取：@RequestParam
• path（用于restful接口）–>请求参数的获取：@PathVariable
• body（不常用）
• form（不常用）
• name：参数名
• dataType：参数类型
• required：参数是否必须传
• value：参数的意思
• defaultValue：参数的默认值

5. @ApiResponses：用于表示一组响应
6. @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
   code：数字，例如400
   message：信息，例如"请求参数没填好"
   response：抛出异常的类
7. @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
8. @ApiModelProperty：描述一个model的属性

启动并访问

启动服务，打开接口文档访问地址