Swagger
说明：学自狂神视频，只做学习记录之用。
目标：
- 了解Swagger的作用和概念
- SpringBoot集成Swagger
Swagger简介
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部
署管理和使用功能强大的 API 从未如此简单。
Swagger
- 号称世界上最流行的Api框架
- RestFul Api文档在线自动生成工具 => Api 文档玉 Api 定义同步更新
- 直接运行，可以在线测试 Api 接口
- 支持多种语言（Java、Php）
项目使用 Swagger 需要 SpringBox
- Swagger2
- UI
SpringBoot 集成 Swagger
1、新建 SpringBoot Web 项目，
2、导入相关依赖，Swagger 集成依赖的是 springfox 下面的依赖包
3、编写一个 Hello 工程
4、配置 Swagger -- config
Swagger2 和 Swagger3 区别
1、依赖不同
swagger2:
<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>
swagger3:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2、开启方式不同
swagger2:
@EnableSwagger2 // 开启Swagger
@SpringBootApplication
public class SwaggerDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerDemoApplication.class, args);
}
}
swagger3:
引入swagger3的依赖会自动开启，无需注解开启
@SpringBootApplication
public class SwaggerDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerDemoApplication.class, args);
}
}
3、访问方式不同，界面不同
swagger2-ui：http://localhost:8082/swagger-ui.html
swagger3-ui：http://localhost:8082/swagger-ui/index.html
4、规范标准不同，配置不同
swagger2使用swagger2规范，swagger3使用的是opeanApi3规范。使用起来区别不大。
public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
public static final DocumentationType OAS_30 = new DocumentationType("openApi", "3.0");
swagger2：new Docket(DocumentationType.SWAGGER_2)
swagger3：new Docket(DocumentationType.OAS_30)
Swagger 配置说明
访问 swagger-ui 页面：
3部分组成--主要配置这三部分：
- groupName：不同使用人配置的标识
- apiInfo：包含使用人信息、项目信息和 swagger 文档生成接口
- select：扫描的内容--方法、实体类
如果不配置 Docket 配置类，会使用默认的 Docket 配置类，默认的
public Docket(DocumentationType documentationType) {
this.apiInfo = ApiInfo.DEFAULT; // apiInfo：会使用默认的
this.groupName = "default"; // groupName：配置标识
this.enabled = true; // enabled：是否开启swagger，默认开启，不过swagger2必须得先注解
this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
this.applyDefaultResponseMessages = true;
this.host = "";
this.pathMapping = Optional.empty();
this.apiSelector = ApiSelector.DEFAULT;
this.enableUrlTemplating = false;
this.vendorExtensions = new ArrayList();
this.globalRequestParameters = new ArrayList();
this.documentationType = documentationType;
}
public ApiInfo(String title, String description, String version, String termsOfServiceUrl, Contact contact, String license, String licenseUrl, Collection<VendorExtension> vendorExtensions) {
this.title = title; // 标题
this.description = description; // 描述
this.version = version; // 版本号
this.termsOfServiceUrl = termsOfServiceUrl; // 使用的网址url--使用项目的url
this.contact = contact; // 作者信息
this.license = license; // 许可证，使用默认的 apache 许可证
this.licenseUrl = licenseUrl; // 许可证网址，使用默认的 apache 网址
this.vendorExtensions = new ArrayList(vendorExtensions);
}
// 默认的apiInfo构造
static {
DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
}
案例：
@Configuration
public class SwaggerConfig {
//配置Swagger的Docker实例
@Bean
public Docket docket(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//设置实例分组名，对象标识
.groupName("zengzx")
.select()
//RequestHandlerSelectors,配置要扫描接口的方式
//basepackage 指定扫描包
//any 扫描全部
//none 不扫描
//withclassannotation 扫描类上注解
//withMethodAnnotation 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo"))
//paths() 过滤路径
//.paths(PathSelectors.ant("/example/**"))
.build();
}
//配置Swagger信息
public ApiInfo apiInfo() {
//作者信息
Contact contact = new Contact("zengzx", "https://www.cnblogs.com/", "[email protected]");
return new ApiInfo("Api Documentation-zengzx",
"Api-信息",
"v1.0",
"https://www.cnblogs.com/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<>());
}
}
问题：如何保证只在生产环境使用 swagger，在正式环境不启用。可以为正式环境减少不必要的资源浪费。
解决：springboot 可以设置多个环境，只要在 application.yaml 配置下说明使用的是 dev 还是 pro 即可，然后可以判断现在使用的环境配置文件时 dev 还是 pro，然后根据需要设置是否打开。
spring:
profiles:
active: dev
// 只要环境配置文件是以 application-dev 规则命名形式，会自动切换识别
@Bean
public Docket docket(Environment environment) {
//设置要显示的swagger环境
Profiles profiles = Profiles.of("dev", "test");
//获取项目的环境,判断是否是需要开启swagger的环境
boolean enable = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("zengzx")
.enable(enable)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo"))
.build();
}
Swagger实战
swagger 主要注解说明：
@Target(ElementType.TYPE) //可以看注解源码是使用在什么类上面的
Api：使用在类上面
ApiOperation：使用在方法上面
ApiModel：使用在实体类上面
ApiModelProperty：使用在实体类属性上面
注解里面属性可以看文档，一般只使用描述就行。
@Api(tags = {"swagger-tags","swagger-tags2"})
public class SwaggerController{
//方法注释
@ApiOperation(value = "user",notes = "swagger")
@GetMapping("/user")
public User user(){
return new User();
}
}
@ApiModel(description = "用户实体类" )
public class User {
@ApiModelProperty(value = "用户名")
public String username;
@ApiModelProperty("实名")
public String realName;
}
Swagger-ui
显示功能：
配置了扫描配置的会扫描出方法类，如果方法类中方法使用了实体类，那么也会将实体类扫描出来，而注解的作用不是说注解了就会扫描，注解只是信息的一个补充或说明，在需要扫描的时候将信息替换或者补充，所有主要是需要配置需要扫描控制类所在的包。
测试功能：
swagger-ui 可以在页面进行接口测试。打开方法点击try it out，按照页面操作即可。比较强大的是后端出错状态什么都能返回。自己去玩。
文档查看和导出功能：
此功能比较重要，可以使用文档查看和导出之外，可以和其他 api 协作管理软件进行协同合作。将扫描的接口和实体类信息导入支持 swagger 或 opeanapi 协议的软件里面。减少开发文档编写工作量。
此处使用--apifox：
