Swagger：搭建SwaggerAPI接⼝⽂档
⽂章⽬录
Swagger
学习⽬标：
了解Swagger的作⽤和概念
了解前后端分离
在SpringBoot中集成Swagger
1.1导语：
相信⽆论是前端还是后端开发，都或多或少地被接⼝⽂档折磨过。前端经常抱怨后端给的接⼝⽂档与实际情况不⼀致。后端⼜觉得编写及维护接⼝⽂档会耗费不少精⼒，经常来不及更新。其实⽆论是前端调⽤后端，还是后端调⽤后端，都期望有⼀个好的接⼝⽂档。但是这个接⼝⽂档对于程序员来说，就跟注释⼀样，经常会抱怨别⼈写的代码没有写注释，然⽽⾃⼰写起代码起来，最讨厌的，也是写注释。所以
仅仅只通过强制来规范⼤家是不够的，随着时间推移，版本迭代，接⼝⽂档往往很容易就跟不上代码了。所以为了解决这⼀问题，引⼊了Swagger。
1.2 Swagger是什么？它能⼲什么？
发现了痛点就要去解决⽅案。解决⽅案⽤的⼈多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接⼝及接⼝相关的信息。再通过Swagger衍⽣出来的⼀系列项⽬和⼯具，就可以做到⽣成各种格式的接⼝⽂档，⽣成多种语⾔的客户端和服务端的代码，以及在线接⼝调试页⾯等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger 描述⽂件，就可以⾃动⽣成接⼝⽂档和客户端服务端代码，做到调⽤端代码、服务端代码以及接⼝⽂档的⼀致性。
但即便如此，对于许多开发来说，编写这个yml或json格式的描述⽂件，本⾝也是有⼀定负担的⼯作，特别是在后⾯持续迭代开发的时候，往往会忽略更新这个描述⽂件，直接更改代码。久⽽久之，这个描述⽂件也和实际项⽬渐⾏渐远，基于该描述⽂件⽣成的接⼝⽂档也失去了参考意义。所以作为Java届服务端的⼤⼀统框架Spring，迅速将Swagger规范纳⼊⾃⾝的标准，建⽴了Spring-swagger项⽬，后⾯改成了现在的Springfox。通过在项⽬中引⼊Springfox，可以扫描相关的代码，⽣成该描述⽂件，进⽽⽣成与代码⼀致的接⼝⽂档和客户端代码。这种通过代码⽣成接⼝⽂档的形式，在后⾯需求持续迭代的项⽬中，显得尤为重要和⾼效。
1.3Swagger简介
前后端分离
Vue + SpringBoot
后端时代：前端只⽤管理静态页⾯；html==> 后端。模板引擎 JSP =>后端是主⼒
前后端分离式时代：
后端 ：后端控制层，服务层，数据访问层 【后端团队】
前端 ：前端控制层，视图层 【前端团队】
伪造后端数据，json。已经存在了，不需要后端，前端⼯程依旧能够跑起来
前端后如何交互 ? ===> API
前后端相对独⽴，松耦合；
前后端甚⾄可以部署在不同的服务器上；
产⽣⼀个问题：
前后端集成联调，前端⼈员和后端⼈员⽆法做到 “即使协商， 尽早解决”，最终导致问题集中爆发；
解决⽅案：
⾸先指定schema[计划的提纲]，实时更新最新API，降低集成的风险；
早些年：指定word计划⽂档；
前后端分离：
前端测试后端接⼝：postman
后端提供接⼝，需要实时更新最新的消息及改动！
1.4 Swaggerr特点：
号称世界上最流⾏的Api框架；
RestFul Api ⽂档在线⾃动⽣成⼯具=>Api⽂档与API定义同步更新
直接运⾏，可以在线测试API接⼝；
⽀持多种语⾔：（Java，Php…）
在项⽬使⽤Swagger需要 springbox；
swagger2
ui
SpringBoot 集成Swagger
1. 新建⼀个SpringBoot = web项⽬
1. 导包
Maven依赖如下，版本⾃选（现在是2.9.2版本）：
<!-- mvnrepository/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- mvnrepository/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2. 在项⽬中配置
2.1 新建⼀个类作为配置类
在配置包config下建⽴名为SwaggerConfig类
@Component
@EnableSwagger2// 开启Swagger2的⾃动配置
public class SwaggerConfig {
}
2.2 配置Swagger实例
Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。@Component
// 开启Swagger2的⾃动配置
@EnableSwagger2
public class SwaggerConfig {
// 配置docket以配置Swagger具体参数
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2);
}
}
2.3 配置API⽂档的信息
通过apiInfo()属性配置⽂档信息：
// 配置docket以配置Swagger具体参数
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
private ApiInfo apiInfo(){
Contact contact =new Contact("联系⼈名字","/联系⼈访问链接","联系⼈邮箱");
// public ApiInfo(String title, String description, String version, String termsOfServiceUrl, Contact contact, String ", String licenseUrl, Collection<VendorExt ension> vendorExtensions)
return new ApiInfo("狂神的SwaggerAPI⽂档",// 标题
"即使再⼩的帆也能远航",// 描述
"v1.0",// 版本
"terms.service.url/组织链接",// 组织链接
contact,// 联系⼈信息
"Apach 2.0 许可",// 许可
"许可链接",// 许可连接
new ArrayList<>());// 扩展
}
}
配置后重启访问可以看到如下：
2.4 配置要扫描的接⼝
构建Docket时通过select()⽅法配置怎么扫描接⼝。
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 通过.select()⽅法，去配置扫描接⼝
//basePackage：指定要扫描的包
//any()：扫描全部
//none()：不扫描
//withClassAnnotation：扫描类上的注解，参数是⼀个注解的反射对象
//withMethodAnnotation：扫描⽅法上的注解
//RequestHandlerSelectors，配置要扫描接⼝的⽅式
.apis(RequestHandlerSelectors.basePackage("com.ller"))
/
/paths()。过滤什么路径
//  .paths(PathSelectors.ant("/westos/**"))
.build();
}
private ApiInfo apiInfo(){
Contact contact =new Contact("联系⼈名字","/联系⼈访问链接","联系⼈邮箱");
// public ApiInfo(String title, String description, String version, String termsOfServiceUrl, Contact contact, String ", String licenseUrl, Collection<VendorE xtension> vendorExtensions) {
return new ApiInfo("Swagger学习",// 标题
"学习演⽰如何配置Swagger",// 描述
"v1.0",// 版本
"terms.service.url/组织链接",// 组织链接
contact,// 联系⼈信息
"Apach 2.0 许可",// 许可
"许可链接",// 许可连接
new ArrayList<>());// 扩展
}
}
重新访问：
除了通过包路径配置扫描接⼝外，还可以通过配置其他⽅式扫描接⼝，这⾥注释⼀下所有的配置⽅式：
any()// 扫描所有，项⽬中的所有接⼝都会被扫描到
none()// 不扫描接⼝
withMethodAnnotation(final Class<?extends Annotation> annotation)// 通过⽅法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求withClassAnnotation(final Class<?extends Annotation> annotation)// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接⼝
basePackage(final String basePackage)// 根据包路径扫描接⼝
2.5 配置接⼝扫描过滤
上述⽅式可以通过具体的类、⽅法等扫描接⼝，还可以配置如何通过请求路径配置：
eturn new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.westos.swagger,controller"))
// 配置如何通过 path过滤即这⾥只扫描请求以 /user开头的接⼝
.paths(PathSelectors.ant("/westos/**"))
.
build();php项目搭建
这⾥的可选值还有：

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。