Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的 Web 服务
RESTful是一种架构的规范与约束、原则，符合这种规范的架构就是RESTful架构
Rest是web服务的一种架构风格；使用HTTP，URI，XML，JSON，HTML等广泛流行的标准和协议；轻量级，跨平台，跨语言的架构设计，它是一种设计风格，不是一种标准，是一种思想。
说明：
| http方法 | 资源操作 | 幂等 | 安全 |
|---|---|---|---|
| GET | SELECT | 是 | 是 |
| POST | INSERT | 否 | 否 |
| PUT | UPDATE | 是 | 否 |
| DELETE | DELETE | 是 | 否 |
幂等性：对同一REST接口多次访问，得到的资源状态是相同的
安全性：对该REST接口访问，不会使服务端资源状态发生改变
优点：
<!--swagger依赖--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!--swagger ui--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
3.0版本
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>
2.编写swagger配置文件
@Configuration
@EnableSwagger2 //开启Swagger2
public class Swagger2Config {
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
* 指定扫描的包路径来定义指定要建立API的目录。
* @return
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(adminApiInfo())
//.enable(false) //enable是否启动Swagger 如果为false，则swagger不能在浏览器中访问
.groupName("adminApi")
.select()
//RequestHandlerSelectors 配置要扫描接口的方式
//basePackage: 指定要扫描的包
//any()：扫描全部
//none()不扫描
//withClassAnnotation: 扫描类上的注解，参数为一个注解的反射对象
//withMethodeAnnotation: 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
//只显示admin下面的路径
.paths(Predicates.and(PathSelectors.regex("/admin/.*")))
.build();
}
private ApiInfo adminApiInfo(){
return new ApiInfoBuilder()
.title("api文档")
.description("系统接口描述")
.version("1.0")
//作者信息
.contact(new Contact("张三","http://baidu.com","12345678@qq.com"))
.build();
}
}3.编写接口请求并运行
访问方式（本地）：http://localhost:8080/swagger-ui.html
使用：
实体类：
@ApiModel("用户实体类")
public class User{
@ApiModelProperty("用户名")
public String username;
}接口方法，参数：
@RestController
public class UserController{
@ApiOperation("User控制类")
@GetMapping(value="/user")
public String getUser(@ApiParam("用户名")String username){
return "名字为："+username;
}
}常用注解：
@Api：修饰整个类，描述Controller的作用,放在类上
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponses：HTTP响应整体描述
@ApiResponse：HTTP响应其中1个描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表
@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
//eg:
@ApiImplicitParam(name="username",value="用户名",required=true)使用Knife4j2.06以上版本，springboot版本必须大于等于2.2.x
作用
1.引入依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
</dependency>2.添加SwaggerConfiguration作为Swagger2的配置类
@Configuration
@EnableSwagger2
@EnableKnife4j
//@EnableSwagger2WebMvc 2.6以上报空指针异常则需要添加
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2) // 选择swagger2版本
.apiInfo(apiInfo()) //定义api文档汇总信息
.select()
.apis(RequestHandlerSelectors
.basePackage("com.example")) // 指定生成api文档的包
.paths(PathSelectors.any()) // 指定所有路径
.build();
}
/**
* 构建文档api信息
*
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("") // 文档标题
.contact(new Contact("", "", "")) //联系人信息
.description("") //描述
.version("1.0.1") //文档版本号
.termsOfServiceUrl("") //网站地址
.build();
}
}3.实现生产环境关闭文档资源
spring: profiles: prod #指定环境 knife4j: production: true #开启屏蔽文档资源
4.实现接口排序
@ApiSupport(order = 序号)@ApiOperationSupport(order = 序号)注：更多详细配置：swagger文档增强工具knife4j使用详解
