**Swagger**
1) 号称世界上最流行的API框架。
2) RestFul API文档在线自动生成工具->Api文档与API定义同步更新。
3) 直接运行，可以在线测试API接口。
[swagger_demo（gitee），记得给个小星星哈！](https://gitee.com/xi_jing/Swagger_demo1)
[swagger_demo（github），记得给个小星星哈！](https://github.com/hnust-xijing/Swagger_demo1)
[swagger官网地址](https://swagger.io/)
在项目中使用Swagger需要springbox;
1) swagger2
2) ui
**SpringBoot集成Swagger**
1,新建一个springBoot Web项目
2，导入相关依赖
```xml
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.10.5</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.10.5</version>
</dependency>
```
3，编写一个Hello工程。
4，编写Swagger==>Config
```java
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}
```
5，测试运行
```java
http://localhost:8080/swagger-ui.html#/hello-controller
```
**配置Swagger**
Swagger的bean实例Docket；
```java
package com.shuang.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;
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
//配置了swagger的docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//配置swagger信息apiInfo
private ApiInfo apiInfo() {
Contact contack=new Contact("江爽","https://www.shishuangzhi.xyz","2894247242@qq.com");
return new ApiInfo(
"爽宝的Swagger API文档",
"看到这个demo的人，能教我追妹子吗，有偿，微信号：js13617293003",
"1.0",
"https://www.shishuangzhi.xyz",
contack,
"Apache 2.0",
"http://www.apache.org/license/LICENSE-2.0",
new ArrayList()
);
}
}
```
**Swagger配置扫描接口**
Docket.select()
```java
//配置了swagger的docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors，配置要扫描接口的方式
//basePackage:指定要扫描的包
//any():扫描全部
//none():不扫描
//withclassAnnotation:扫描类上的注解
.apis(RequestHandlerSelectors.basePackage("com.shuang.controller"))
//paths()，过滤什么路径
.paths(PathSelectors.ant("/shuang/**"))
.build();
}
```
我只希望我的Swagger在生产环境中使用，在发布的时候不使用？
1）判断是不是生产环境 flag=false
2）注入enable(flag)
```java
//配置了swagger的docket的bean实例
//core.env结尾的
@Bean
public Docket docket(Environment environment){
//设置要显示的Swagger环境
Profiles profiles=Profiles.of("dev","test");
//获取项目的环境
//通过environment.acceptsProfiles判断是否处于自己设置的环境中。
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)//enable是否启动Swagger,如果为false,则Swagger不能在浏览器中访问。
.select()
//RequestHandlerSelectors，配置要扫描接口的方式
//basePackage:指定要扫描的包
//any():扫描全部
//none():不扫描
//withclassAnnotation:扫描类上的注解
.apis(RequestHandlerSelectors.basePackage("com.shuang.controller"))
//paths()，过滤什么路径
.paths(PathSelectors.ant("/shuang/**"))
.build();
}
```
**配置API文档的分组**
.groupName("爽宝")
如何配置多个分组；多个Docket实例即可。
```java
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
@Bean
public Docket docket4(){
return new Docket(DocumentationType.SWAGGER_2).groupName("D");
}
```
实体类
```java
package com.shuang.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
```
controller
```java
package com.shuang.controller;
import com.shuang.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello(){
return "hello";
}
//主要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中。
@PostMapping("/user")
public User user(){
return new User();
}
//Operation接口，不是放在类上的,是方法
@ApiOperation("Hello控制类")
@GetMapping("/hello2")
public String hello2(@ApiParam("用户名") String username){
return "hello"+username;
}
@ApiOperation("post测试类")
@PostMapping("/postt")
public User hello3(@ApiParam("用户名") User user){
return user;
}
}
```
总结：
1，我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息。
2，接口文档实时更新。
3，可以在线测试。
Swagger是一个优秀的工具，几乎所有大公司都有使用它。
【注意点】在正式发布的时候，关闭Swagger！！出于安全，也节约内存。
