前后端分离
后端时代:前端值用管理静态页面;html==>后端。模板引擎jsp==>后端是主力
Swagger自动生成API文档 ,就是用来测试接口的
前后端分离时代:
-
后端:后端控制层,服务层,数据访问层【后端团队】
-
后端写完接口,前端去调用,给前端一个路径(接口名)
-
前端:前端控制层,视图层【前端团队】
-
这就是一个接口
号称世界上最流行的Api框架
1. 创建项目
2.导入依赖
io.springfox
springfox-swagger2
2.7.0
io.springfox
springfox-swagger-ui
2.7.0
ui就是不同的界面皮肤,想用哪种就导入哪种的ui
3.编写一个Hello工程
@RestController
public class HelloController {
@RequestMapping(value = "/hello")
public String hello(){
return "hello";
}
}
4.编写一个配置类config层(以后只要需要配置类,包名都叫config)
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}
5.测试
http://localhost:8080/swagger-ui.html
配置Swangger信息
1.需要在配置类中配置swagger实例bean
@Bean //配置Swagger的docket的Bean实列
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2);
}
2.可以通过apiInfo()属性配置文档信息 (也放到配置类里)
//配置Swagger2信息 = apiInfo
private ApiInfo apiInfo(){
//作者信息 联系人名称 联系人访问地址 联系人邮箱
Contact contact = new Contact("冯宝宝","https://blog.csdn.net/qq_45511798?type=blog","fjq229@foxmail.com");
return new ApiInfo(
"冯宝宝的SwaggerAPI文档", //标题
"在实践中学习", //描述
"1.0", //版本
"https://blog.csdn.net/qq_45511798?type=blog", //组织链接
contact, //联系人信息
"Apache 2.0", //许可
"http://www.apache.org/licenses/LICENSE-2.0", //许可链接
new ArrayList() //扩展
);
}
3.Docket 实例关联上 apiInfo()
@Bean //配置Swagger的docket的Bean实列
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
就是说要去调用这个api
4重启项目,访问测试 http://localhost:8080/swagger-ui.html 看下效果;
5.Swangger配置扫描接口
构建Docket时通过select()方法配置怎么扫描接口。 @Bean //配置Swagger的docket的Bean实列
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//查询扫描以下方法
.select()
//通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
//basePackage:指定扫描的包
//any():扫描全部
//none():不扫描
.apis(RequestHandlerSelectors.basePackage("com.lxyk.controller")) //扫描这个包下所有的接口
//paths():过滤扫描路劲
//.paths(PathSelectors.any(""))
.build();
}
重启项目测试,由于我们配置根据包的路径扫描接口,所以我们只能看到一个类
除了通过包路径配置扫描接口外,还可以通过配置其他方式扫描接口,这里注释一下所有的配置方式:
basePackage(final String basePackage) // 根据包路径扫描接口 any() // 扫描所有,项目中的所有接口都会被扫描到 none() // 不扫描接口 // 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求 withMethodAnnotation(final Class extends Annotation> annotation) // 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口 withClassAnnotation(final Class extends Annotation> annotation)除此之外,我们还可以配置接口扫描过滤:
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.lxyk.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/ss开头的接口
.paths(PathSelectors.ant("/ss/**"))
.build();
}
这里的可选值还有
any() // 任何请求都扫描 none() // 任何请求都不扫描 regex(final String pathRegex) // 通过正则表达式控制 ant(final String antPattern) // 通过ant()控制
6.配置Swagger开关
通过enable()方法配置是否启用swagger,如果是false,swagger将不能在浏览器中访问了
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false) //配置是否启用Swagger,如果是false,在浏览器将无法访问
.select()
.apis(RequestHandlerSelectors.basePackage("com.lxyk.controller"))
.build();
}
7.分组
根据不同的分组显示不同的页面
1、如果没有配置分组,默认是default。通过groupName()方法即可配置分组:
.groupName("冯宝宝")
访问:http://localhost:8081/swagger-ui.html 2、 如何配置多个分组?配置多个分组只需要配置多个docket即可:
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
重启项目
访问:http://localhost:8081/swagger-ui.html
8.实体配置1、新建一个实体类
//@Api("注释")
@ApiModel("用户实体类")
@Data
@EqualsAndHashCode
@AllArgsConstructor
@NoArgsConstructor
public class User {
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
}
@ApiModel("用户实体类"):页面就会展示有个用户名,有个密码
2、只要这个实体在请求接口的返回值上(即使是泛型),都能映射到实体项中:
@RestController
public class HelloController {
@GetMapping(value = "/hello")
public String hello(){
return "hello";
}
//只要我们的接口中,返回值中存在实体类,他就会被扫描到Swagger中
@PostMapping(value = "/user")
public User user(){
return new User();
}
}
9.常用注解
| Swagger注解 | 简单说明 |
|---|---|
| @Api(tags = “xxx模块说明”) | 作用在模块类上 |
| @ApiOperation(“xxx接口说明”) | 作用在接口方法上 |
| @ApiModel(“xxxPOJO说明”) | 作用在模型类上:如VO、BO |
| @ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上,hidden设置为true可以隐藏该属性 |
| @ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上,类似@ApiModelProperty |
我们也可以给请求的接口配置一些注释
1、在HelloWorld控制类中的接口添加api接口注释
@ApiOperation("Hello控制接口")
@GetMapping("/hello2")
public String hello2(@ApiParam("用户名") String username) {
return "hello" + username;
}
@ApiOperation("get测试")
@GetMapping("/get")
public User getUser(@ApiParam("用户") User user) {
return user;
}
在它的参数上也加了注解,测试的时候就会出来
注意:看到Api开头的注解就是Swagger 的
还可以用其他的皮肤,只需要引入它的依赖就可以
com.github.xiaoymin swagger-bootstrap-ui1.9.1



