撒子是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", "[email protected]");
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){}
