Swagger 3.0与SpringBoot 2.6.1集成
世界上最流行的Api框架
RestFul Api文档在线自动生成工具=>Api文档与Api定义同步更新
直接运行,可以在线测试Api接口(controller(RequestMapping))
Swagger官网https://swagger.io/
1. 在项目中使用Swagger需要导入jar包
springBox-swagger2
springBox-swagger ui
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</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>
2. 编写一个Controller
@RestController
public class HelloController {
// /error默认请求
@RequestMapping(value = "/hello")
public String hello(){
return "hello";
}
}
主启动类需添加@EnableOpenApi注解
@EnableOpenApi
@SpringBootApplication
public class Springboot09SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run (Springboot09SwaggerApplication.class, args);
}
}
3. 配置SwaggerConfig
@Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig{
//RequestHandlerSelectors)配置扫描接口的方式
/*RequestHandlerSelectors.basePackage("com.ji.controller"):指定扫描的包
RequestHandlerSelectors.any() 扫描全部
RequestHandlerSelectors.none() 不扫描
RequestHandlerSelectors.withClassAnnotation(RestController.class) 扫描类上的注解 @Target(ElementType.TYPE)
RequestHandlerSelectors.withMethodAnnotation (GetMapping.class) 扫描方法上的注解 @Target(ElementType.METHOD)
* */
//paths :过滤什么路径
//配置SwaggerDocket Bean实例
//配置
@Bean
public Docket docket(Environment environment){
//多环境 开关swagger environment
//设置要显示swagger 的环境
Profiles profiles=Profiles.of ("dev","test");
//判断当前环境是否是profiles中显示swagger的环境
boolean b = environment.acceptsProfiles (profiles);
return new Docket (DocumentationType.SWAGGER_2)
.apiInfo (apiInfo ())
.groupName ("jsp") //配置Api文档分组 多个Docket分组
.enable (b) //是否启动swagger 如果为false则swagger不能再浏览器中访问
.select ()
.apis (RequestHandlerSelectors.basePackage("com.ji.controller"))
.paths (PathSelectors.ant ("/ji/**"))
.build ();
}
@Bean
public Docket docket1(){
return new Docket (DocumentationType.SWAGGER_2)
.apiInfo (apiInfo ())
.groupName ("hcy"); //配置Api文档分组
}
@Bean
public Docket docket2(){
return new Docket (DocumentationType.SWAGGER_2)
.apiInfo (apiInfo ())
.groupName ("zzz"); //配置Api文档分组
}
//配置swagger信息
private ApiInfo apiInfo(){
return new ApiInfo ("Jsp SwaggerLogger",
"学习",
"17.0",
"https://www.cnblogs.com/Liuyunsan/",
new Contact ("jsp", "https://www.cnblogs.com/Liuyunsan/", "2315510122@qq.com"), //作者信息
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList ());
}
}
4. Models
@RestController
public class HelloController {
//Operation接口 给controller 方法增加注释
@ApiOperation ("helloController控制类")
// /error默认请求
@GetMapping(value = "/ji/hello")
public String hello(){
return "hello";
}
@PostMapping(value = "/ji/hello")
//只要我们的接口中,返回值张存在实体类,它就会被扫描到swagger中
public User user(@ApiParam("用户名") String username){
return new User();
}
}
//@Api("注释")
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
5. 总结
- 可以通过Swagger给比较难理解的属性或者接口,增加注释信息
- 接口文档实时更新
- 可以在线测试
- 正式发布时,需要关闭Swagger(出于安全考虑和性能考虑)