springboot集成Swagger
Swagger
目标：
- 了解Swagger的作用与概念
- 了解前后分离
- 在SpringBoot中集成Swagger
Swagger简介
前后端分离
Vue + SpringBoot
后端时代： 前端只需要管理静态页面；Html==>后端。 模板引擎JSP=>后端才是主力
前后端分离时代：
- 后端：后端控制层，服务层，数据访问层【后端团队】
- 前端：前端控制层，视图层【前端团队】
2.1.伪造后端数据，json。 json的存在，不需要后端，前端工程师依旧能够跑起来项目 - 前端后端如何交互？ ==> API
- 前后端相对独立，松耦合；
- 前后端甚至可以部署在不同的服务器上；
产生的问题：
- 前后端集成联调，前端人员和后端人员无法做到 “ 及时协商，尽早解决”，最终导致问题爆发
解决方案
- 首先制定schema[计划的提纲]，实时更新最新的API，降低集成的风险；
- 早些年：制定Word计划文档；
- 前后端分离：
- 前端测试后端接口：postman
- 后端提供接口，需要实时更新最新的消息及改动
Swagger
- 号称世界上最流行的api框架
- Restful API 文档在线自动生成工具=>API文档与API定义同步更新
- 直接运行，可以在线测试APi接口；
- 支持多种语言： java ，Php。。。。。。。。
在项目中使用swagger需要springbox；
- swagger2
- swaggeer ui
springboot集成Swagger
-
新建一个springboot web项目
-
导入相关依赖
<!-- 以下为springboot 3.0 版本 使用start--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> <!-- 以下为springboot 3.0 版本一下使用的jar包--> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>3.0.0</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>3.0.0</version> </dependency> -
编写Hello word工程
-
配置Swagger ==> Config
4.1 老版
//swagger配置类 @Configuration @EnableSwagger2 //开启swagger public class SwaggerConfig { }4.2 新版启动类要加
@SpringBootApplication @EnableOpenApi //springboot3.0以后加这个注解 public class SpringbootSwaggerDemoApplication { public static void main(String[] args) { SpringApplication.run(SpringbootSwaggerDemoApplication.class, args); } } -
测试运行
访问 swagger-ui.html
配置swagger信息
//配置swagger 信息=apiinfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("waves","","yjtwd999@.com");
return new ApiInfo("waves 的Swagger api文档"
,"描述"
,"版本信息1.0"
,"https://www.cnblogs.com/wdyjt/"
,contact
,"Apache 2.0"
,"http://www.apache.org/licenses/LICENSE-2.0"
,new ArrayList<>());
}
Swagger 配置扫描接口
Docket.select()
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors 配置要扫描接口的方式
//basePackage 配置指定要扫描的包
//any 全部扫描
//none 全部不扫描
//withClassAnnotation 扫描类上的注解 参数是一个注解的反射对象
//withMethodAnnotation 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.waves.springbootswagger"))
//paths（） 过滤作用 ，只扫描/hello/**
.paths(PathSelectors.ant("/hello/**"))
.build();
}
配置是否启动Swagger
.enable(false) 配置是否启动swagger，如果为false，则swagger不可再浏览器中被访问
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false)
.apis(RequestHandlerSelectors.basePackage("com.waves.springbootswagger"))
//paths（） 过滤作用 ，只扫描/hello/**
.paths(PathSelectors.ant("/hello/**"))
.build();
根据application环境配置是否启动Swagger，全部配置
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
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;
//swagger配置类
@Configuration
@EnableSwagger2 //开启swagger
@EnableOpenApi
public class SwaggerConfig {
//配置Swagger的Docket的Bean实例
@Bean
public Docket docket(Environment environment){
//设置要显示的Swagger环境 可以多个 of("dev","test")
Profiles profiles = Profiles.of("dev");
//通过environment.acceptsProfiles判断是否处在自己设定的环境
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)
.select()
//RequestHandlerSelectors 配置要扫描接口的方式
//basePackage 配置指定要扫描的包
//any 全部扫描
//none 全部不扫描
//withClassAnnotation 扫描类上的注解 参数是一个注解的反射对象
//withMethodAnnotation 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.waves.springbootswagger"))
//paths（） 过滤作用 ，只扫描/hello/**
.paths(PathSelectors.ant("/hello/**"))
.build();
}
//配置swagger 信息=apiinfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("waves","","yjtwd999@.com");
return new ApiInfo("waves 的Swagger api文档"
,"描述"
,"版本信息1.0"
,"https://www.cnblogs.com/wdyjt/"
,contact
,"Apache 2.0"
,"http://www.apache.org/licenses/LICENSE-2.0"
,new ArrayList<>());
}
}
配置多个APi分组
//配置多个分组
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("涛1");
}
//配置Swagger的Docket的Bean实例
@Bean
public Docket docket(Environment environment){
//设置要显示的Swagger环境 可以多个 of("dev","test")
Profiles profiles = Profiles.of("dev");
//通过environment.acceptsProfiles判断是否处在自己设定的环境
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)
.groupName("涛")
.select()
//RequestHandlerSelectors 配置要扫描接口的方式
//basePackage 配置指定要扫描的包
//any 全部扫描
//none 全部不扫描
//withClassAnnotation 扫描类上的注解 参数是一个注解的反射对象
//withMethodAnnotation 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.waves.springbootswagger"))
//paths（） 过滤作用 ，只扫描/hello/**
.paths(PathSelectors.ant("/hello/**"))
.build();
}
User实体类
package com.waves.springbootswagger.dao.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
public String Username;
@ApiModelProperty("密码")
public String Password;
}
Controller
package com.waves.springbootswagger.controller;
import com.waves.springbootswagger.dao.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@ApiOperation("apiControllere")
@RestController
@RequestMapping("/hello")
public class HelloControlleer {
@GetMapping("/hello")
public String hello(){
return "hello Word";
}
@PostMapping("/User")
public User user(){
return new User();
}
@PostMapping("/User2")
@ApiOperation("这个注解可以放在类上也可以放在方法上")
public String user2(@ApiParam("参数用户名") String username){
return "hello"+username;
}
}
总结
1.我们可以通过Swagger给一些把较难理解的属性或者接口，添加注释信息、
2.接口文档实时更新
3.可以在线测试
Swagger是一个很优秀的工具，几乎所有大公司都有使用它
但是需要注意的是：在正式发布的时候，一定要关闭Swagger
出于安全考虑，而且节省运行内存
