撒子是Swagger?
- 使用swagger可以帮助我们更简单的API接口的开发
- API文档与API定义同步更新,可以在线测试API接口(API接口就是controller的requestmapping)
Swagger其实就是我们前后端分离时来实现前后端开发的信息及时更新Api的一个框架,是前后端的唯一联系。比如我们后端写了一些controller接口,前端就能通过访问swagger-ui来及时的查看到。
Swagger的页面主要有四个部分:
- Swagger信息:开发者的一些信息什么的。
- 接口信息:我们后端写的controller接口的信息。
- 实体类信息:就是实体类信息啦,不过只有在controller中返回值有实体类的才会有显示。
- 分组:对应着一个个的Docket。
Swagger的使用
1、新建一个SpringBoot-web项目
2、导入相关依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
3、配置Swagger
在SwaggerConfig中配置Swagger的基本信息:
package com.lyr.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;
import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//配置Swagger信息
private ApiInfo apiInfo(){
Contact contact = new Contact("lyr", "https://blog.csdn.net/wan_ide", "1111223@qq.com");
return new ApiInfo(
"Lyr's Api Documentation",
"面朝大海,然后春暖花开",
"1.0",
"https://blog.csdn.net/wan_ide",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
效果:
Swagger配置扫描接口
RequestHandlerSelectors 配置要扫描接口的方式:
- basePackage:指定要扫描的包
- any():描述全部
- none():不扫描
- withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
- withMethodAnnotation:描述方法的注解
package com.lyr.swagger.config;
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 org.springframework.web.bind.annotation.RequestMapping;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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;
import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//.enable(false) 是否启动Swagger
.enable(flag)
.select()
//RequestHandlerSelectors 配置要扫描接口的方式
//basePackage:指定要扫描的包
//any():描述全部
//none():不扫描
//withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
//withMethodAnnotation:描述方法的注解
//.apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
.apis(RequestHandlerSelectors.basePackage("com.lyr.swagger.controller"))
//paths() 过滤扫描路径
//.paths(PathSelectors.ant("/lyr/**"))
.build();
}
}
使Swagger在生产环境中使用,在发布时不使用
1、新建一个application-dev.properties,生产环境时的配置,设置端口号为8081
2、新建一个application-pro.properties,发布环境时的配置,设置端口号为8082
3、在application.properties中激活生产环境时的配置:
spring.profiles.active=pro
在SwaggerConfig中配置根据环境启动Swagger:
package com.lyr.swagger.config;
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 org.springframework.web.bind.annotation.RequestMapping;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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;
import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment){
//设置要显示的Swagger环境
Profiles profiles = Profiles.of("pro");
//通过environment.acceptsProfiles判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)
.select()
.apis(RequestHandlerSelectors.basePackage("com.lyr.swagger.controller"))
.build();
}
}
效果:
当生产时(激活dev)可以访问,当发布时(激活pro)不可以访问
配置API文档的分组:
.groupName("lyr")
配置多个分组就new多个Docket。
Swagger中的注解
- @ApiModel("用户实体类"):给Models加上注释,用在实体类上。但是要求返回值中存在实体类,才会被扫描到。
- @ApiModelProperty("用户名"):给实体类中的属性加上注释,用在属性上。
- @ApiOperation("hello的控制类"):给controller中的接口加上注释,只能放在方法上。
- @ApiParam("用户名"):public String hello(@ApiParam("用户名")String username){}