Swagger
1. Swagger-UI基本介绍
- Swagger-UI是HTML, Javascript, CSS的一个集合,可以动态地根据注解生成在线API文档。
- 官网:https://swagger.io/tools/swagger-ui/
- 相关资料:狂神说集成Swagger
2. 常用注解
@Api
:用于修饰Controller类,生成Controller相关文档信息@ApiModel
:用于修饰Model类@ApiOperation
:用于修饰Controller类中的方法,生成接口方法相关文档信息@ApiParam
:用于修饰接口中的参数,生成接口参数相关文档信息@ApiModelProperty
:用于修饰实体类的属性,当实体类是请求参数或返回结果时,直接生成相关文档信息
3. 使用方式
添加项目依赖
-
Springfox3.0版本:使用
{host}/swagger-ui/
访问文档,并且不再需要@EnableSwagger2
注解<!--Swagger-UI API文档生产工具--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>
-
Springfox2.x版本:使用
{host}/swagger-ui.html
or{host}/swagger-ui
访问文档<!--Swagger-UI API文档生产工具--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.4</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.4</version> </dependency>
-
参考文档:https://github.com/LalithK90/Swagger3-Documentation-Springboot-Sample
添加Swagger-UI配置
-
Swagger对生成API文档的范围有三种不同的选择
- 生成指定包下面的类的API文档
- 生成有指定注解的类的API文档
- 生成有指定注解的方法的API文档
-
SwaggerConfig配置文件:
@Configuration public class SwaggerConfig { @Bean public Docket createRestApi(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) //配置是否启用Swagger,如果是false,在浏览器将无法访问,动态配置当项目处于test、dev环境时显示swagger,处于prod时不显示 .enable(true) // 配置分组名称 .groupName("Test") // 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口 .select() //为当前包下controller生成API文档 .apis(RequestHandlerSelectors.basePackage("com.study.mall.controller")) /* 为有@Api注解的Controller生成API文档 .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) 为有@ApiOperation注解的方法生成API文档 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) */ //配置如何通过path过滤 .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { Contact contact = new Contact("SiKun", "http://www.sikun.site","psikun@foxmail.com"); return new ApiInfoBuilder() .title("坤坤小淘气") .description("mall项目学习") .contact(contact) .version("1.0") .build(); } }
-
配置详解:
-
.enable(true)
:配置是否启用Swagger,如果是false,在浏览器将无法访问,动态配置当项目处于test、dev环境时显示swagger,处于prod时不显示 -
.groupName("Test")
:配置分组的名称,如果要配置多个分组,可以返回多个Docket@Bean public Docket docket1(){ return new Docket(DocumentationType.SWAGGER_2).groupName("group1"); } @Bean public Docket docket2(){ return new Docket(DocumentationType.SWAGGER_2).groupName("group2"); }
-
.select()
:通过.select()方法,去配置扫描接口,RequestHandlerSelectors
配置如何扫描接口 -
.apis()
:配置扫描接口//为指定包下controller生成API文档 .apis(RequestHandlerSelectors.basePackage("com.study.mall.controller")) //为有@Api注解的Controller生成API文档 .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) //为有@ApiOperation注解的方法生成API文档 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
-
.paths(PathSelectors.any())
:配置如何通过path过滤any() // 任何请求都扫描 none() // 任何请求都不扫描 regex(final String pathRegex) // 通过正则表达式控制 ant(final String antPattern) // 通过ant()控制
-
.build()
:执行构建
-
-
ApiInfo
类:一些基本的信息,显示到首页.contact(Contact contact)
:需要传递一个Contact
对象,查看源码发现,构造函数需要name
,url
,email
三个参数