Swagger 3
后端：控制层 controller、服务层 service、数据访问层 dao
前端：前端控制层、视图层
前后端交互：通过 API 接口
前后端相对独立，松耦合，甚至可以部署在不同的服务器上
随之产生的问题：前后端联调，前端人员和后端人员无法做到及时协商，尽早解决
解决方案：
首先指定 schema(计划)，实时更新最新的 API，降低集成风险
早些年：指定 word 计划文档
前后端分离：
前端测试后端接口数据是否正确：postman
后端提供接口，需要实时更新最新的消息和改动
于是 Swagger 应运而生
号称历史上最流行的 api 框架
RestFul Api 文档在线生成工具=》Api 文档与 Api 定义同步更新
直接运行，可以在线测试 Api 接口
支持多种语言
SpringBoot 项目整合 swagger2 需要用到两个依赖：springfox-swagger2 和 springfox-swagger-ui，用于自动生成 swagger 文档。
springfox-swagger2：这个组件的功能用于帮助我们自动生成描述 API 的 json 文件
springfox-swagger-ui：就是将描述 API 的 json 文件解析出来，用一种更友好的方式呈现出来。
此版本的亮点：
Spring5，Webflux 支持（仅支持请求映射，尚不支持功能端点）。
Spring Integration 支持。
SpringBoot 支持 springfox Boot starter 依赖性（零配置、自动配置支持）。
支持 OpenApi 3.0.3。
零依赖。几乎只需要 spring-plugin，swagger-core ，现有的 swagger2 注释将继续工作并丰富 openapi3.0 规范。
兼容性说明：
需要 Java 8
需要 Spri
ng5.x（未在早期版本中测试）
需要 SpringBoot 2.2+（未在早期版本中测试）
应用主类添加注解 @EnableOpenApi (swagger2 是 @EnableSwagger2)
swagger 配置类 SwaggerProperties.class，与 swagger2.xx 版本有差异，具体看下文
自定义一个配置类 SwaggerConfiguration.class,看下文
访问地址：http://localhost:8080/swagger-ui/index.html
(swagger2.xx 版本访问的地址为 http://localhost:8080/swagger-ui.html)
=======================================================================
Maven 项目中引入 springfox-boot-starter 依赖：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
spring:
application:
name: springfox-swagger
server:
port: 8080
===== 自定义 swagger 配置 =====
swagger:
enable: true
application-name: ${spring.application.name}
application-version: 1.0
application-description: springfox swagger 3.0 整合 Demo
try-host: http://localhost:${server.port}
**在 Swagger 提供的 ui 界面，其中的 Swagger 信息模块我们可以自定义信息内容
我们只需要在 Swagger 配置类 SwaggerConfig 中实例化 Docket 类队对象的 bean 实例，通过配置 ApiInfo 类的信息然后传入 Docket 的 bean 实例即可**
@Configuration
@EnableOpenApi //开启 Swagger3
public class SwaggerConfig {
//配置 Swagger 的 Docket 的 bean 实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());//配置 Swagger 信息
}
//配置 Swagger 信息
/*String title, String description,
String version, String termsOfServiceUrl,
Contact contact, String license,
String licenseUrl,
Collection<VendorExtension> vendorExtensions*/
private ApiInfo apiInfo() {
return new ApiInfo(
"大忽悠项目",
"大忽悠的 Swagger API 文档",
"2.0",//版本信息
"https://blog.csdn.net/m0_53157173",//团队信息的 url
new Contact("大忽悠", "https://blog.csdn.net/m0_53157173", "3076679680@qq.com"),//作者信息
/Contact(String name, String url, String email)/
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<VendorExtension>());
}
}
我们在这个 ui 界面中，可以看到扫描了两个 controller 接口；
一个是默认的/error 请求，也就是我们启动 springboot 主程序未加配置默认访问 8080 端口的默认 controller
剩余的就是我们自己再 controller 层写的请求映射了
//配置 Swagger 的 Docket 的 bean 实例
@Bean
public Docket docket()
{
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//配置 Swagger 信息
.select()
/**
apis():指定扫描的接口
RequestHandlerSelectors:配置要扫描接口的方式
*/
.apis(RequestHandlerSelectors.basePackage("com.Controller"))
/**
paths():过滤路径
PathSelectors:配置过滤的路径
*/
.paths(PathSelectors.any())
.build();
}
其中.select().apis.paths.build 是一套组合进行使用
只有被过滤筛选出来并且在指定包下面的请求路径才会显示在页面上
我么通过 Docket 对象的.enable 方法来配置 swagger 是否启动
@Bean
public Docket docket()
{
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//配置 Swagger 信息
.enable(false)//enable 是否启动 swagger,如果为 false,那么浏览器中无法访问 swagger
.select()
.apis(RequestHandlerSelectors.basePackage("com.Controller"))
.paths(PathSelectors.any())
.build();
}
首先要判断是不是开发环境，可以设置一个 flag 表示用来表示：flag=1 即表示生产环境
然后将 flag 的值传给 enable(flag)
首先在 resources 目录下新建两种 springboot 配置文件
开发环境：application-dev.properties
server.port=8081
正式环境：application-pro.properties
server.port=8082
然后在主配置文件 application.properties 中激活开发环境
spring.profiles.active=dev
然后我们到 SwaggerConfig 中的 docket()方法中添加代码：
首先给该方法传一个参数 Environment 的实例
Environment environment
首先设置要配置的 Swagger 环境：这里可以添加多个环境
Profiles.of("dev", "test");
然后通过 environment.acceptsProfiles 方法判断是否处在上一步设定的 dev/test 环境中，返回一个 boolean 的值，我们用 flag 接收
boolean flag = environment.acceptsProfiles(profiles);
然后修改 enable 中的参数为 flag，即通过 flag 来判断是否开启 Swagger
.enable(flag)//通过 flag 判断是否开启
完整代码：
@Configuration
@EnableOpenApi //开启 Swagger3
public class SwaggerConfig {
//配置 Swagger 的 Docket 的 bean 实例
@Bean
public Docket docket(Environment environment)
{
//设置要配置的 Swagger 环境
Profiles p = Profiles.of("dev", "test");
//通过 environment.acceptsProfiles 判断是否处在自己设定的环境中
boolean flag = environment.acceptsProfiles(p);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//配置 Swagger 信息
.enable(flag)
.select()
.apis(RequestHandlerSelectors.basePackage("com.Controller"))
.paths(PathSelectors.any())
.build();
}
//配置 Swagger 信息
private ApiInfo apiInfo() {
return new ApiInfo(
"大忽悠项目",
"大忽悠的 Swagger API 文档",
"2.0",//版本信息
"https://blog.csdn.net/m0_53157173",//团队信息的 url
new Contact("大忽悠", "https://blog.csdn.net/m0_53157173", "3076679680@qq.com"),//作者信息
/Contact(String name, String url, String email)/
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<VendorExtension>());
}
}
然后启动主程序测试：由于激活了 dev 开发环境，所以访问 localhost:8081/swagger-ui.html
成功开启 swagger，如果我们修改主配置文件，激活 pro 正式发布环境
spring.profiles.active=pro
再次重启主程序测试，访问端口 8082 对应的地址 localhost:8082/swagger-ui.html
无法进入，因为 pro 环境不在我们配置的 test/dev 环境中，所以无法开启
1. 设置默认组名
可以看到，我们默认只有一个组且组名为 default
我们可以在 docket 通过.groupName 中设置组名
@Bean
public Docket docket(Environment environment)
{
//设置要配置的 Swagger 环境
Profiles p = Profiles.of("dev", "test");
//通过 environment.acceptsProfiles 判断是否处在自己设定的环境中
boolean flag = environment.acceptsProfiles(p);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//配置 Swagger 信息
.enable(flag)
.groupName("大忽悠")
.select()
.apis(RequestHandlerSelectors.basePackage("com.Controller"))
.paths(PathSelectors.any())
.build();
}
2. 配置多个组
**上述我们成功修改了组名，但是只有一个组，如果我们想要多个组呢？
观察代码可以知道，一个 Docket 实例就对应着一个组，因此我们配置多个 docket 就对应着多个组**
@Bean
public Docket docket1() {
return new Docket(DocumentationType.SWAGGER_2).groupName("大忽悠 1 号");
}
@Bean
public Docket docket2() {
return new Docket(DocumentationType.SWAGGER_2).groupName("大忽悠 2 号");
}
只要我们的 controoler 层方法中，返回值中存在实体类，他就会被扫描到 Swagger 中
@RestController
public class UserControoler
{
//只要我们的接口中，返回值中存在实体类，他就会被扫描到 Swagger 中
@GetMapping("/User")
public User showUser(User u)
{
return u;
}
}
现在的问题是，页面显示出来的返回的 User 类，如果是非常复杂的情况下，没有注释就很难看懂，这样就有了注解来进行解释
评论