文章目录
- 前言
- 一、Swagger
- 二、SpringBoot集成Swagger
-
- 1.引库
- 2.导入依赖
- 3.配置Swagger
- 4.进入测试
- Swagger配置扫描接口
- 配置是否启动Swagger
- 配置API文档分组
- 实体类的配置
- 文档注解
- 总结
前言
说起Swagger就不得不说前后端分离
当前最主流的前后端分离技术栈：Vue+Springboot
后端时代：
前端只用管理静态页面:html
最后统一交给后端，后端将其修改为jsp，在整个过程中，后端充当主力
前后端分离时代：
后端：后端控制层，服务层，数据访问层【后端团队】
前端：前端控制层，视图层【前端团队】
前端可以自定义一些伪后端数据：json,在写的时候就存在，不需要后端，前端工程依旧能够跑起来
那么前端后端如何交互？
此时我们可以考虑API
前后端分离好处：
- 前后端相对独立，松耦合
- 前后端设置可以部署在不同的服务器上
产生的问题：
- 前后弹集成联调，前端人员和后端人员无法做到及时协商，尽早解决，最终导致问题爆发；
解决方式：
-
首先指定schema[计划的提纲]，实时更新最新的API，降低集成风险
-
早期：指定word计划文档
-
前后端分离时期：
前端测试后端接口：postman
后端提供接口，需要实时更新最新的消息及改动
一、Swagger
- 号称世界上最流行的Api框架
- RestFul Api 文档在线自动生成工具，Api文档与Api定义同步更新
- 直接运行，可以在线测试API接口
- 支持多种语言：（Java,php等）
官网：http://swagger.io/
二、SpringBoot集成Swagger
1.引入库
2.导入依赖
- swagger2
- ui
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
12345
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
12345
3.配置Swagger
@EnableSwagger2 用来开启Swagger2
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}
12345
4.进入测试
http://localhost:8080/swagger-ui.html
# 配置Swagger基本信息 Swagger的Bean实例Docket:
package com.kuang.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 //开启Swagger2
public class SwaggerConfig {
@Bean
public Docket docket(){
//配置了Swagger的Docket的Bean实例
// DocumentationType documentationType = new DocumentationType();
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//配置swagger信息需要apiInfo类
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("wql","https://www.baidu.com/","845906996@qq.com");
return new ApiInfo(
"wql的Swagger日记",
"本人描述",
"v1.0",
"https://www.baidu.com/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
1234567891011121314151617181920212223242526272829303132333435363738394041
Swagger配置扫描接口
RequestHandlerSelectors()配置要扫描接口的方式
basePackage()指定扫描的包
any()扫描全部的包
none()都不扫描
withClassAnnotation()扫描类上的注解，参数是注解的反射对象
withMethodAnnotation()扫描方法上的注解
123456
Docket.select()
1
@Bean
public Docket docket(){
//配置了Swagger的Docket的Bean实例
// DocumentationType documentationType = new DocumentationType();
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors,配置要扫描接口的方式
//basePackage指定扫描的包
//any扫描全部的包
//none()都不扫描
//withClassAnnotation()扫描类上的注解，参数是注解的反射对象
//withMethodAnnotation()扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
//paths()，过滤路径，只让/kuang开头的请求通过
.paths(PathSelectors.ant("/kuang/**"))
.build();
}
12345678910111213141516171819
配置是否启动Swagger
enable是否启动swagger，如果为false，则swagger不能在浏览器中访问
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false)
123
swagger启动失败
那么如果我们希望Swagger在某一个环境中使用，在其他时候不使用怎么办
dev环境下：
server.port=8081
1
pro环境下
server.port=8080
1
application.properties文件
spring.profiles.active=dev
1
此时我们处于dev环境下，我们希望swagger在dev环境下能使用，在其他环境下不能使用
Profiles profiles = Profiles.of("dev","test");
//获取生产环境
//通过environment.acceptsProfiles(profiles)判断自己是否处在指定环境
boolean flag = environment.acceptsProfiles(profiles);
1234
将enable()中的参数值设置为flag，这样当我们处于dev与test环境下时swagger默认开启，其他情况下默认关闭
进入dev环境
进入pro环境
配置API文档分组
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("hello")
123
如果我们想配置多个分组怎么办呢？
创建多个docket对象，设置不同的组名
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
123456789101112
可以看见页面中出现了不同的组别，每个组别之间互不干扰，利于合作开发，每个人扫描自己的包，做自己的事情
实体类的配置
User类
package com.kuang.swagger.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
public String username;
public String password;
}
1234567891011121314151617
HelloController中：
//只要返回值中存在实体类，他就会被扫描到Swagger中
@PostMapping("/user")
public User user(){
return new User("zs","123");
}
12345
查看Swagger:
文档注解
为了方便交互，方便文档阅读，我们可以为文档添加说明信息
@ApiModel(“用户实体类”)为实体类添加说明信息
@ApiModelProperty(“用户名”)为实体类中的属性添加说明信息
@Api(tags = “控制器-hello”)为接口添加说明信息
@ApiOperation(“hello请求”)为请求增加说明信息
@ApiParam(“hello请求中的name”)为请求中的参数增加说明信息
实体类
package com.kuang.swagger.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
//@Api("注释")
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
123456789101112131415161718192021
HelloController:
package com.kuang.swagger.controller;
import com.kuang.swagger.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
//给文档加注释
@Api(tags = "控制器-hello")
@RestController
public class HelloController {
@GetMapping("/")
public String HelloWord(){
return "Hello World";
}
//只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
@PostMapping("/user")
public User user(){
return new User("zs","123");
}
@ApiOperation("hello请求")
@GetMapping("hello")
public String hello(@ApiParam("hello请求中的name") String username){
return "hello"+username;
}
}
123456789101112131415161718192021222324252627282930
添加注释后展示：
总结
- 我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息
- 接口文档实时更新
- 可以在线测试
注意点：
在正式发布的时候，需要关闭Swagger，一是出于安全考虑，，二是节省内存
1万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
