Swagger使用教程及Swagger增强工具knife4j_swagger knife

重点掌握：编写swagger的配置文件，理解每个配置的作用

课外知识须知

Swagger官网：

什么是swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger让部署管理和使用功能强大的API变得非常简单。
简单来说，就是后端给前端提供的一个可以查看各种接口的方法、类型等。

作用：

1. 接口的文档在线自动生成。
2. 功能测试。
   
   
   

什么是RESTful 面向资源

简单的说：RESTful是一种架构的规范与约束、原则，符合这种规范的架构就是RESTful架构。

REST是英文representational state transfer(表现层状态转变)或者表述性状态转移，准确的说是Resource Representational State Transfer（资源表述性状态转移），就是资源在网络中以某种表现形式进行状态转化。Rest是web服务的一种架构风格；使用HTTP，URI，XML，JSON，HTML等广泛流行的标准和协议；轻量级，跨平台，跨语言的架构设计，它是一种设计风格，不是一种标准，是一种思想。

资源
“资源”是RESTful中最核心的概念之一。在RESTful概念中，互联网中的每一样信息都可以定义为资源，比如文本、图片、音频、视频等。而这些资源又都可以对应一个特定的URI(统一资源定位符)，URI为每一个资源的地址或独一无二的识别符。

表现层
针对上面的“资源”，我们要进行相应的呈现，而且可以采用多种的呈现形式，而这些呈现形式就叫做“表现层”。
就拿文本为例，我们可以呈现为JSON格式、XML格式、HTML格式，甚至二进制格式等。这就是表现层所做的事情。

状态转化
资源通常放在服务器端，而客户端对服务器资源的增、删、改、查等操作，便涉及到资源状态的转化。这个过程便是“ 状态转化”。

我们以HTTP协议为例（RESTful不仅仅适用HTTP协议，只不过经常以HTTP协议为衬托），客户端可通过一些操作让服务器端的资源发生变化。而这整个过程，便是“表现层状态转化”。

在HTTP中，提供了四种常见的操作方式：GET、POST、PUT、DELETE。这四种操作方式分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。

URI和URL区别：

URI和URL的区别
URI和URL的区别比较与理解

URI只是一种概念，怎样实现无所谓，只要它唯一标识一个资源就可以了。
URL是URI的一个子集，是Internet上描述信息资源的字符串，主要用在各种WWW客户程序和服务器程序上，是URI概念的一种实现方式。


URI和URL都定义了资源是什么，但URL还定义了该如何访问资源。URL是一种具体的URI，它是URI的一个子集，它不仅唯一标识资源，而且还提供了定位该资源的信息。URI 是一种语义上的抽象概念，可以是绝对的，也可以是相对的，而URL则必须提供足够的信息来定位，是绝对的。
只要能唯一标识资源的就是URI，在URI的基础上给出其资源的访问方式的就是URL

以上还理解不了，看下面这个按例，然后继续看上面的内容

博址推荐

Swagger简明教程

SpringBoot集成Swagger

1、新建SpringBoot项目，导入swagger依赖

IDEA建立一个SpringBoot Web工程

 <!--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>

1
2
3
4
5
6
7
8
9
10
11
12
13

如果是3.0直接导入下面一个依赖即可

2、编写swagger的配置文件

当然了你可以配置一下 Swagger信息可参考如下
配置原理请参考此视频

@Configuration
@EnableSwagger2
public class Swagger2Config {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 指定扫描的包路径来定义指定要建立API的目录。
     * @return
     */
    @Bean
    public Docket coreApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(adminApiInfo())
                .groupName("adminApi")
                .select()
                //只显示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","728831102@qq.com"))
                .build();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

编写一个hello工程

启动项目 测试运行：http://localhost:8080/swagger-ui.html

为什么访问此路径可以出现这个页面，这个页面哪来的

Swagger配置Swagger部分信息及效果

Swaggeri配置扫描接口

这块感兴趣可参考视频

配置是否启动Swagger

我只希望我的Swagger在生产环境中使用，在发布的时候不使用？
. 判断是不是生产环境flag=false
. 注入enable(flag)

配置API文档的分组
（groupName可以进行分组以区分后端开发者，如果有多个后端开发者，可以在Swagger2Config类里写多个Docket对象然后通过@Bean注入，不同的Docket对象代表不同的分组）

如何配置多个分组：多个Docket实例即可

为什么要分组：实际工作多人开发(系统协作开发)，Bean可能来自很多类，最终都得被Spring托管，你写的Bean是管你的扫描的，别人写的Bean是管别人扫描的。
每个人(一个个Bean)扫描自己的包，对别人没影响

实体类信息的配置


这样是没有注释的，不太清楚每个字段含义，如何加上实体类的相关注释呢



给接口方法、参数加注释

Swagger常用注解

更详细的说明请参见官方注解说明文档
Swagger常用注解1
swagger常用注解2

1、@ApiModel
使用场景：在实体类上使用，标记类时swagger的解析类
概述：提供有关swagger模型的其它信息，类将在操作中用作类型时自动内省

2、@ApiModelProperty
使用场景：使用在被 @ApiModel 注解的模型类的属性上。表示对model属性的说明或者数据操作更改
概述：添加和操作模型属性的数据

 /**
	 * Student类 学生实体类
*/
@ApiModel(value = "Student",description = "用户实体类")
public class Student implements Serializable {
  @ApiModelProperty(value = "学号")
  private Integer id; //学号
  @ApiModelProperty(value = "姓名")
  private String name; //姓名
  //日期的格式 年-月-日
  @ApiModelProperty(value = "生日")
  @DateTimeFormat(pattern = "yyyy-MM-dd")
  private Date birthday; //生日
 }
1
2
3
4
5
6
7
8
9
10
11
12
13
14

3、@ApiOperation
使用场景：使用在方法上，表示一个http请求的操作
概述：用来表示Controller类下的http请求方法

 @ApiOperation("添加学生信息")
 @PostMapping(value = "/student")
 public void AddStudent(Student student) {

  studentService.AddStudent(student);
 }
1
2
3
4
5
6

4、@ApiParam
使用场景：在 Rest 接口上或 Rest 接口参数前边使用
概述：为 Rest 接口参数添加其它元数据(导入到 yapi 中不会被解析)

 @ApiOperation("判断验证码是否正确")
 @RequestMapping(value = "/UpdatePassword" , method = RequestMethod.POST)
 public CommonResult updatePassword(
 @ApiParam(value = "手机号码"，required = true) @RequestParam String userPhone,
 @ApiParam(value = "验证码",required = true) @RequestParam String authCode){

 return userMemberService.updatePassword(userPhone,authCode);
 }

1
2
3
4
5
6
7
8
9

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数描述

@ApiModel：用对象来接收参数

@ApiProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值

@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

mplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值

@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

Swagger增强工具knife4j

knife4j官方文档

Spring Boot 基础教程：集成 Knife4j
swagger文档增强工具knife4j使用详解

先说一下引入这个依赖我们都能干嘛
Swagger 功能增强：接口搜索、离线文档下载、全局参数设置等功能…
①可以搜索接口名称快速定位接口(搜索功能)
②可以下载markdown、HTML、word 等格式文件(下载功能)
③。。。。。。自己去发现，更多详情戳我

①引入依赖 你可以去maven官网搜knife4j 我这里是springboot项目

注意：引入knife4j后会自动引入swagger相关依赖，所以无需再手动引入swagger相关依赖，否则会引起版本冲突，在使用knife4j的一些增强功能时会报错

<!-- knife4j接口文档 -->
<!-- <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
 -->
<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.2</version>
</dependency>

1
2
3
4
5
6
7
8
9
10
11
12
13
14

②添加SwaggerConfiguration作为Swagger2的配置类
这块就是我上面配置文件的基础上在加点注解啥的
关于这块配置类上的注解网上都不太一样，我也没此需求，也没验证，后期遇到我在更新。
需要的伙伴自行百度，能弄成效果即可
（解决SpringBoot使用knife4j无法引入@EnableSwagger2WebMvc：之前已经引入过了swagger2了，再引入Knife4j就会导致注解无法引入，把原来swagger2的东西注释掉后，这个注解就能正常引入了。）
(Knife4j 2.0.7默认引入swagger2.10.5,而swagger2.1版本开始引入了@EnableSwagger2WebMvc,废弃了@EnableSwagger2)

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
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;

/**
 * @类名: SwaggerConfiguration
 * @包名: com.blogs.web.blogsweb.config
 * @IDE的名称: IntelliJ IDEA
 * @当前项目的名称: blogsweb
 * @作者: YangMian
 * @时间: 2020/5/12 14:31
 * @版本: 1.0.0
 * <p>说明: </p>
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
//@EnableSwagger2WebMvc 有用这个注解的 
@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.blogsweb.web"))  // 指定生成api文档的包
                .paths(PathSelectors.any())     // 指定所有路径
                .build()
                ;
    }

    /**
     * 构建文档api信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("")     // 文档标题
                .contact(new Contact("", "", ""))   //联系人信息
                .description("")      //描述
                .version("1.0.1")     //文档版本号
                .termsOfServiceUrl("")     //网站地址
                .build();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

当然了你也可以先不做任何配置 输入localhost:8080/doc.html进入如下页面

详细网址

必看