SpringBoot集成使用swagger

什么是swagger？

简单地说，就是用来生成接口文档、测试接口的。其目的是用来协助前后端的集成联调，争取及时协商，尽早更改。
在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。

swagger框架长什么样？

Swagger Hub： 集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。
Swagger Inspector: 和postman差不多的一个东西，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
Swagger Editor: 类似于markdown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
Swagger UI: 提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

swagger有什么特点？

1. 它是一个文档在线自动生成工具。API文档与API定义同步更新。
2. 最流行的API框架
3. RestFul风格
4. 可直接运行，在线测试 API接口
5. 支持多种语言（java、PHP等）

项目中集成swagger

1. 创建SpringBoot项目时要勾选web依赖
2. 在项目中使用swagger需要springbox，在maven仓库中搜索Springfor Swagger2和Springfor Swagger UI
3. 导入依赖配置Springfor Swagger2和Springfor SwaggerUI

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</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>

4. 集成swagger。建立一个config包，在该包下新建一个SwaggerConfig配置类，并为该类加注解：@Configuration和 @EnableSwagger2（开启Swagger2）
5. 测试运行。访问http://localhost:8080/swagger-ui.html

配置Swagger

swagger的bean实例Docket（就这一个实例）；
在SwaggerConfig配置类中写入：

//配置swagger的Docket的bean实例
@Bean
public Docket docket(){
	return new Docket(DocumentationType.SWAGGER_2)
		.apiInfo(apiInfo());
}

//配置swagger信息=>apiInfo
private ApiInfo apiInfo(){
	//作者信息
	Contact contact = new Contact(name:"作者名字",url:"让其指向服务组织就行",email:"email地址");
	return new ApiInfo(
				title:"Api Documentation",//标题
				description:"Api Documentation",//描述
				version:"1.0",//版本号
				termsOfServiceUrl:"urn:tos",//服务组织url（项目链接）
				contact,//作者信息
				license:"Apache 2.0",//开源版本号
				licenseUrl:"http://www.apache.org/LICENSE-2.0",//开源版本号的url
				new ArrayList()//一些其他的信息
		);
}

配置扫描接口

通过具体的配置对接口进行扫描，使得所扫描的部分更加具体精准

.enable(false) //enable为是否启用swagger，如果为false，则为不启动（不对当前范围接口进行扫描）

如何只在生产环境中使用swagger，在发布的时候不使用？

1. 判断是否为生产环境，定义boolean变量flag。在多环境开发中，在Docket类中设置参数（Environment environment）
2. 设置要返回的swagger环境
3. 将flag注入到enable。enable(flag)

Profiles profiles = Profiles.of("dev","test")
boolean flag = environment.acceptsProfiles(profiles);
enable(flag);

注意：项目正式发布的时候，为了信息安全以及节省内存，一定要关闭swagger

如何给实体类生成相应注解？

只需加注解：
@ApiModel(“实体类名”)——用在类上
@ApiModelProperty(“字段名”)——用在相应字段上