SpringMVC注解配置Swagger2步骤及相关知识点
2017-05-03 18:56
477 查看
Swagger2的功能不多说了,百度一下随处可见,配置步骤也十分简单,但一些点百度到的很多都不太详细,个人进行了一些补充
1、pom.xml添加swagger2依赖(个人一般直接到http://search.maven.org/搜索artifactid点最新版本copy到pom里)
2、添加设置swagger2配置类
package pers.graduation.config;
import com.google.common.collect.Sets;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;
/**
* Created by Wilson on 2017/5/2.
*/
@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan(basePackages = "pers.graduation.controller")
public class SwaggerConfig extends WebMvcConfigurationSupport {
@Bean
public Docket commonDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("通用API接口文档")
.apiInfo(apiInfo("提供通用接口"))
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("pers.graduation.controller.common"))
.paths(PathSelectors.any())
.build();
}
@Bean
public Docket normalUserDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("普通用户API文档")
.apiInfo(apiInfo("提供普通用户接口"))
.protocols(Sets.newHashSet("https","http"))
.produces(Sets.newHashSet("html/text"))
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("pers.graduation.controller.candidate"))//设置生成的Docket对应的Controller为candidate下的所有Controller
.paths(PathSelectors.any())
.build();
}
@Bean
public Docket companyUserDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("企业用户API接口文档")
.apiInfo(apiInfo("提供企业用户接口"))
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("pers.graduation.controller.company"))
.paths(PathSelectors.any())
.build();
}
//设置文档信息
private ApiInfo apiInfo(String desc) {
return new ApiInfo(
"Test Website", //标题名称
desc, //文档描述
"1.0.1", //版本号,自定义
"http://blog.csdn.net/z28126308", //许可人URL
contact(), //联系方式实体类
"Wilson", //许可人,许可证
"http://blog.csdn.net/z28126308"); //许可URL
}
//设置联系方式
private Contact contact() {
return new Contact("Wilson", "http://blog.csdn.net/z28126308", "z28126308@163.com");
}
}
Docket类的方法:
Docket groupName(String var):设置栏目名
Docket apiInfo(ApiInfo apiInfo):设置文档信息
Docket pathMapping(String path):设置api根路径
Docket protocols(Set<String> protocols):设置协议,Sets为com.goolge.common下的类,Sets.newHashSet("https","http")相当于new HashSet(){{add("https");add("http");}};
ApiSelectorBuilder select():初始化并返回一个API选择构造器
ApiSelectorBuilder类的方法:
ApiSelectorBuilder apis(Predicate<RequestHandler> selector):添加选择条件并返回添加后的ApiSelectorBuilder对象
ApiSelectorBuilder paths(Predicate<String> selector):设置路径筛选,该方法中含一句pathSelector = and(pathSelector, selector);表明条件为相与
RequestHandlerSelectors类的方法:
Predicate<RequestHandler> any():返回包含所有满足条件的请求处理器的断言,该断言总为true
Predicate<RequestHandler> none():返回不满足条件的请求处理器的断言,该断言总为false
Predicate<RequestHandler> basePackage(final String basePackage):返回一个断言(Predicate),该断言包含所有匹配basePackage下所有类的请求路径的请求处理器
PathSelectors类的方法:
Predicate<String> any():满足条件的路径,该断言总为true
Predicate<String> none():不满足条件的路径,该断言总为false
Predicate<String> regex(final String pathRegex):符合正则的路径
不讲太多,有兴趣的去看源码
3、设置swagger-ui.html默认路径,servlet的配置文件添加
<mvc:annotation-driven></mvc:annotation-driven>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars"/>
swagger-ui.html位于springfox-swagger-ui jar包中的META-INF/resources/目录下,项目编译后swagger-ui.html将添加到classpath的/META-INF/resources/下,所以添加mapping="/webjars/**" 可通过localhost:端口号/项目名/swagger-ui.html打开SwaggerUI
4、常用注解
Swagger所有注解并非必须,若不加就只显示类目/方法名/参数名没有注释而已,但若注解中含@ApiParam不对应@RequestParam将无效果
@Api:注解controller,value为@RequestMapping路径
@ApiOperation:注解方法,value为简要描述,notes为全面描述,hidden=true Swagger将不显示该方法,默认为false
@ApiParam:注解参数,hidden=true Swagger参数列表将不显示该参数,name对应参数名,value为注释,defaultValue设置默认值,allowableValues设置范围值,required设置参数是否必须,默认为false
@ApiModel:注解Model
@ApiModelProperty:注解Model下的属性,当前端传过来的是一个对象时swagger中该对象的属性注解就是ApiModelProperty中的value
@ApiIgnore:注解类、参数、方法,注解后将不在Swagger UI中显示
效果图(若要传送对象作为参数,只需添加@ModelAttribute或@RequestBody):
传送对象参数:
model:
Controller方法:
Swagger
1、pom.xml添加swagger2依赖(个人一般直接到http://search.maven.org/搜索artifactid点最新版本copy到pom里)
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency>
2、添加设置swagger2配置类
package pers.graduation.config;
import com.google.common.collect.Sets;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;
/**
* Created by Wilson on 2017/5/2.
*/
@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan(basePackages = "pers.graduation.controller")
public class SwaggerConfig extends WebMvcConfigurationSupport {
@Bean
public Docket commonDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("通用API接口文档")
.apiInfo(apiInfo("提供通用接口"))
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("pers.graduation.controller.common"))
.paths(PathSelectors.any())
.build();
}
@Bean
public Docket normalUserDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("普通用户API文档")
.apiInfo(apiInfo("提供普通用户接口"))
.protocols(Sets.newHashSet("https","http"))
.produces(Sets.newHashSet("html/text"))
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("pers.graduation.controller.candidate"))//设置生成的Docket对应的Controller为candidate下的所有Controller
.paths(PathSelectors.any())
.build();
}
@Bean
public Docket companyUserDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("企业用户API接口文档")
.apiInfo(apiInfo("提供企业用户接口"))
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("pers.graduation.controller.company"))
.paths(PathSelectors.any())
.build();
}
//设置文档信息
private ApiInfo apiInfo(String desc) {
return new ApiInfo(
"Test Website", //标题名称
desc, //文档描述
"1.0.1", //版本号,自定义
"http://blog.csdn.net/z28126308", //许可人URL
contact(), //联系方式实体类
"Wilson", //许可人,许可证
"http://blog.csdn.net/z28126308"); //许可URL
}
//设置联系方式
private Contact contact() {
return new Contact("Wilson", "http://blog.csdn.net/z28126308", "z28126308@163.com");
}
}
Docket类的方法:
Docket groupName(String var):设置栏目名
Docket apiInfo(ApiInfo apiInfo):设置文档信息
Docket pathMapping(String path):设置api根路径
Docket protocols(Set<String> protocols):设置协议,Sets为com.goolge.common下的类,Sets.newHashSet("https","http")相当于new HashSet(){{add("https");add("http");}};
ApiSelectorBuilder select():初始化并返回一个API选择构造器
ApiSelectorBuilder类的方法:
ApiSelectorBuilder apis(Predicate<RequestHandler> selector):添加选择条件并返回添加后的ApiSelectorBuilder对象
ApiSelectorBuilder paths(Predicate<String> selector):设置路径筛选,该方法中含一句pathSelector = and(pathSelector, selector);表明条件为相与
RequestHandlerSelectors类的方法:
Predicate<RequestHandler> any():返回包含所有满足条件的请求处理器的断言,该断言总为true
Predicate<RequestHandler> none():返回不满足条件的请求处理器的断言,该断言总为false
Predicate<RequestHandler> basePackage(final String basePackage):返回一个断言(Predicate),该断言包含所有匹配basePackage下所有类的请求路径的请求处理器
PathSelectors类的方法:
Predicate<String> any():满足条件的路径,该断言总为true
Predicate<String> none():不满足条件的路径,该断言总为false
Predicate<String> regex(final String pathRegex):符合正则的路径
不讲太多,有兴趣的去看源码
3、设置swagger-ui.html默认路径,servlet的配置文件添加
<mvc:annotation-driven></mvc:annotation-driven>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars"/>
swagger-ui.html位于springfox-swagger-ui jar包中的META-INF/resources/目录下,项目编译后swagger-ui.html将添加到classpath的/META-INF/resources/下,所以添加mapping="/webjars/**" 可通过localhost:端口号/项目名/swagger-ui.html打开SwaggerUI
4、常用注解
Swagger所有注解并非必须,若不加就只显示类目/方法名/参数名没有注释而已,但若注解中含@ApiParam不对应@RequestParam将无效果
@Api:注解controller,value为@RequestMapping路径
@ApiOperation:注解方法,value为简要描述,notes为全面描述,hidden=true Swagger将不显示该方法,默认为false
@ApiParam:注解参数,hidden=true Swagger参数列表将不显示该参数,name对应参数名,value为注释,defaultValue设置默认值,allowableValues设置范围值,required设置参数是否必须,默认为false
@ApiModel:注解Model
@ApiModelProperty:注解Model下的属性,当前端传过来的是一个对象时swagger中该对象的属性注解就是ApiModelProperty中的value
@ApiIgnore:注解类、参数、方法,注解后将不在Swagger UI中显示
效果图(若要传送对象作为参数,只需添加@ModelAttribute或@RequestBody):
传送对象参数:
model:
private String telephone; @Column private String email; @Column private Long companyId; @Transient private ComCompany comCompany; @Transient private List<PositionWelfare> welfareList;
Controller方法:
@ResponseBody @RequestMapping(value = "/per-addPosition", method = RequestMethod.POST) @ApiOperation(value = "添加职位") public Object addPosition(@ModelAttribute ComPosition position, @RequestParam String[] welfareName) {
Swagger
相关文章推荐
- 基于注解配置的SpringMVC编程步骤:
- SpringMVC_01 SpringMVC五大组件、SpringMVC编程步骤(不使用注解进行配置)、SpringMVC编程步骤(利用注解进行配置)、参数获取、响应数据
- springmvc中的相关配置,注解驱动等
- SSH深度历险(十一) AOP原理及相关概念学习+xml配置实例(对比注解方式的优缺点)
- 不使用注解配置SpringMVC环境
- Spring框架中利用注解进行自动装配的环境配置步骤和常见问题
- 基于注解配置简单的SpringMVC+Mybatis
- SSH深度历险(十一) AOP原理及相关概念学习+xml配置实例(对比注解方式的优缺点)
- springMVC 注解事务配置
- 基于注解的Spring MVC整合Hibernate(所需jar包,spring和Hibernate整合配置,springMVC配置,重定向,批量删除)
- 秀外慧中的springMVC(二)---springMVC的注解配置例子
- SpringMVC学习笔记(2) 框架配置+HelloWorld(注解版)
- SpringMVC 注解配置
- Springmvc 提高性能的配置去掉静态文件和只要需要的注解[不太确定]
- SpringMVC框架搭建步骤以及注解功能实现
- SpringMVC基于注解的配置
- springMVC基于注解配置教程一
- 基于注解的springmvc配置例子
- SSH深度历险(十) AOP原理及相关概念学习+AspectJ注解方式配置spring AOP
- 缓存初解(五)---SpringMVC基于注解的缓存配置--web应用实例