认识Swagger
文章目录
前言
提示:以下是本篇文章正文内容,下面案例可供参考
一、Swagger简介
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。因为互联网时代的快速发展,从以前后端渲染变成了前端渲染,开发也不再是后端的主力,前端也同等重要了,前后端分离开发流行起来了。那么前后端的分离,前端和后端的协调非常的重要。为了避免打架,API接口成了它们之间唯一的联系,API文档变成了前后端开发人员联系的纽带,变得越来越重要。而Swagger便是一款便于书写api接口文档的一个框架。
二、使用步骤
1.创建一个springboot项目(记得测试),导入依赖
代码如下(示例):
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
这里使用最新版的话swagger-ui.html页面不能访问,用最新版要更改一些设置,可以自行查找
2.编写Config类(SwaggerConfig)
代码如下(示例):
package com.tao.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
import java.util.ArrayList;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
//配置了swagger的Docket的bean实例
//这里配置了swagger的配置信息
@Bean
public Docket docket(){
//作者信息
Contact contact = new Contact("Tao",
"https://blog.csdn.net/weixin_46459899",
"aaaa@qq.com");
ApiInfo apiInfo=new ApiInfo(
"Api Documentation",
"优秀的判断力来自经验,但经验来自于错误的判断。",
"2.0+",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
//这些swagger的信息配置要学会看源码来配置
//.apiInfo配置我们的swagger接口的一些信息
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo);
}
}
成功后访问(swagger-ui.html),页面如下
3、配置扫描接口以及开关
- 配置扫描接口
public class SwaggerConfig {
//配置了swagger的Docket的bean实例
//这里配置了swagger的配置信息=apiInfo
@Bean
public Docket docket(){
//作者信息
Contact contact = new Contact("Tao",
"https://blog.csdn.net/weixin_46459899",
"aaaa@qq.com");
ApiInfo apiInfo=new ApiInfo(
"Api Documentation",
"优秀的判断力来自经验,但经验来自于错误的判断。",
"2.0+",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
//这些swagger的信息配置要学会看源码来配置
//.apiInfo配置我们的swagger接口的一些信息
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
//RequestHandlerSelectors,配置要扫描接口的方式,然后后点击build方法执行
//any():扫描全部
//none():一个都不扫描
//basePackage:指定要扫描的包 (常用)
//withClassAnnotation:扫描类上的注解
//withMethodAnnotation:扫描方法上的注解类
.apis(RequestHandlerSelectors.basePackage("com.tao.swagger.controller"))
//过滤路径,即这些路径不会被扫描
//.paths(PathSelectors.ant("/请求/**"))
.build();
//select()和build()之间是只有三个方法,继续用其它方法要放在select()前,select和build是一套
}
}
- swagger的开关开启(swagger的开启只有在前后端的开发测试阶段要用到,等到产品上线后,
我们需要将swagger关闭,那么我们就要设置多个环境)
这里为开发环境,端口号设置为8081
这里为上线环境
此时为开发阶段,将环境激活为开发
在SwaggerConfig类中添加判断此是产品的环境
//swagger只有在开发阶段即测试阶段才需要用到,上线后我们不用swagger,所以要设置我们的swagger环境
Profiles profiles=Profiles.of("dev");
boolean flag=environment.acceptsProfiles(profiles);
并在Docket中添加.enable(flag)的方法
public class SwaggerConfig {
//配置了swagger的Docket的bean实例
//这里配置了swagger的配置信息=apiInfo
@Bean
public Docket docket(Environment environment){
//作者信息
Contact contact = new Contact("Tao",
"https://blog.csdn.net/weixin_46459899",
"aaaa@qq.com");
ApiInfo apiInfo=new ApiInfo(
"Api Documentation",
"优秀的判断力来自经验,但经验来自于错误的判断。",
"2.0+",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
//swagger只有在开发阶段即测试阶段才需要用到,上线后我们不用swagger,所以要设置我们的swagger环境
Profiles profiles=Profiles.of("dev");
boolean flag=environment.acceptsProfiles(profiles);
//这些swagger的信息配置要学会看源码来配置
//.apiInfo配置我们的swagger接口的一些信息
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.enable(flag)
.select()
//RequestHandlerSelectors,配置要扫描接口的方式,然后后点击build方法执行
//any():扫描全部
//none():一个都不扫描
//basePackage:指定要扫描的包 (常用)
//withClassAnnotation:扫描类上的注解
//withMethodAnnotation:扫描方法上的注解类
.apis(RequestHandlerSelectors.basePackage("com.tao.swagger.controller"))
//过滤路径,即这些路径不会被扫描
//.paths(PathSelectors.ant("/请求/**"))
.build();
//select()和build()之间是只有三个方法,继续用其它方法要放在select()前,select和build是一套
}
- swagger分组和注释的用法
分组
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
//分组,工作中要用到
.groupName("Tao")
.enable(flag)
注释
@ApiModel实体类上(pojo可以注释)
@ApiModelProperty(“用户名”) 实体类的属性值
@ApiOperation(“你好”) controller中的接口可以使用到
@ApiParam(“用户名+用户密码”)参数
总结
- 我们可以通过Swagger给比较难理解的属性或者接口,增加注释信息
- 接口文档可以实时更新
- 可以在线测试
【注意点:在项目发布时,要把swagger关闭,这是为了出于安全考虑!!!也是为了节省运行内存】