Swagger与Knife4j知识概括

Swagger与Knife4j知识概括

前后端分离简介：

• 前后端职责：
  ①前端 -> 前端控制层、视图层
  ②后端 -> 后端控制层、服务层、数据访问层
• 前后端描述：
  ①前后端通过API进行交互
  ②前后端相对独立且松耦合
• 产生的问题：前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发
• 解决方案：定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险
• 链接：动态生成最新版本API文档的服务器

Swagger简介:

• 号称世界上最流行的API框架
• Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
• 直接运行，在线测试API
• 支持多种语言 （如：Java，PHP等）
• 链接：swagger官网
• 相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。
• Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，提醒下大家在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。

Swagger使用

使用Swagger：

• 要求：jdk 1.8 + 否则swagger2无法运行
• 添加Maven依赖

<!-- swagger核心jar包-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- swagger界面jar包-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

• 使用Swagger需要编写一个配置类来配置 Swagger

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
}

• 访问http://localhost:8080/swagger-ui.html 可以看到swagger的界面。
  

配置Swagger：

• Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2);
}

• 可以通过apiInfo()属性配置文档信息

//配置文档信息
private ApiInfo apiInfo() {
   Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
   return new ApiInfo(
           "Swagger学习", // 标题
           "学习演示如何配置Swagger", // 描述
           "v1.0", // 版本
           "http://terms.service.url/组织链接", // 组织链接
           contact, // 联系人信息
           "Apach 2.0 许可", // 许可
           "许可链接", // 许可连接
           new ArrayList<>()// 扩展
  );
}

• Docket 实例关联上apiInfo()

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

配置扫描接口：

• 构建Docket时通过select()方法配置怎么扫描接口。

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.george.swagger.controller"))
      .build();
}

--------------RequestHandlerSelectors的可选值还有：--------------
any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口

• 除此之外我们还可以配置接口扫描过滤：

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/lin开头的接口
      .paths(PathSelectors.ant("/lin/**"))
      .build();
}

-------PathSelectors的可选值还有：-------
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

配置Swagger开关：

• 通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}

• 动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示。

@Bean
public Docket docket(Environment environment) {
   // 设置要显示swagger的环境
   Profiles of = Profiles.of("dev", "test");
   // 判断当前是否处于该环境
   // 通过 enable() 接收此参数判断是否要显示
   boolean b = environment.acceptsProfiles(of);
   
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(b) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}

配置API分组：

• 如果没有配置分组，默认是default，可以通过groupName()方法配置分组：

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....
}

• 配置多个分组只需要配置多个docket即可。

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

实体配置：

• 新建一个实体类

@ApiModel("用户实体")
public class User {
   @ApiModelProperty("用户名")
   public String username;
   @ApiModelProperty("密码")
   public String password;
}

• 只要这个实体在请求接口的返回值上（即使是泛型）都能映射到实体项中。

@RequestMapping("/getUser")
public User getUser(){
   return new User();
}

• 注意：
  ①并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。
  ②
  <1>@ApiModel为类添加注释
  <2>@ApiModelProperty为类属性添加注释

Swagger常用注解

常用注解简介：

• Swagger的所有注解定义在io.swagger.annotations包下
• 我们也可以给请求的接口和javabean类配置一些注释，这样的话可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读！
• 下面列一些经常用到的：

Swagger注解	简单说明
@Api	用在请求的类上表示对类(controller类)的说明。tags=“说明该类的作用，可以在UI界面上看到的注解”，value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”
@ApiOperation	用在请求的方法(controller类的方法)上说明方法的用途和作用。value=“说明方法的用途、作用”，notes=“方法的备注说明”
@ApiModel	用于响应类(javaBean类)上表示一个返回响应数据的信息
@ApiModelProperty	用在属性上，描述响应类的属性(javaBean类的方法或属性)
@ApiImplicitParams	用在请求的方法(controller类的方法)上，表示一组参数说明
@ApiImplicitParam	用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
@ApiResponses	用在请求的方法(controller类的方法)上，表示一组响应
@ApiResponse	用在@ApiResponses注解中，用于表达一个的响应信息
@ApiIgnore	用于类或者方法(controller类的方法或controller类)上，可以不被swagger显示在页面上
@ApiParam	作用在参数、方法和字段(cotroller类的方法参数)上，类似@ApiImplicitParam

• 个别注解详解：
  ①其中@ApiParam和@ApiImplicitParam的功能是相同的，但是@ApiImplicitParam的适用范围更广

@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息       
    name：参数名
    value：参数的汉字说明、解释
    required：参数是否必须传
    paramType：参数放在哪个地方
        · header --> 请求参数的获取：@RequestHeader
        · query --> 请求参数的获取：@RequestParam
        · path（用于restful接口）--> 请求参数的获取：@PathVariable
        · body（不常用）
        · form（不常用）    
    dataType：参数类型，默认String，其它值dataType="Integer"       
    defaultValue：参数的默认值


@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
    code：数字，例如400
    message：信息，例如"请求参数没填好"
    response：抛出异常的类

@ApiParam	作用在参数、方法和字段上
	name：参数名称，参数名称将从 filed/method/parameter 名称中派生，但你可以覆盖它，路径参数必须始终命名为它们所代表的路径部分
	value：参数简单描述
	defaultValu：描述参数默认值
	allowableValues：可接收参数值限制，有三种方式,取值列表，取值范围
	required：是否为必传参数, false:非必传; true:必传
	access：参数过滤，请参阅:io.swagger.core.filter.SwaggerSpecFilter
	allowMultiple：指定参数是否可以通过多次出现来接收多个值
	hidden：隐藏参数列表中的参数
	example：非请求体(body)类型的单个参数示例
	example：参数示例，仅适用于请求体类型的请求
	type：添加覆盖检测到类型的功能
	format：添加提供自定义format格式的功能
	allowEmptyValue：添加将格式设置为空的功能
	readOnly：添加被指定为只读的能力
	collectionFormat：添加使用 array 类型覆盖 collectionFormat 的功能

• 案例：

--------------------------javabean类-------------------------
@ApiModel(value = "User", description = "用户")
public class User implements Serializable{

    private static final long serialVersionUID = 1546481732633762837L;

    /**
     * 用户ID
     */
    @ApiModelProperty(value = "用户ID", required = true)
    @NotEmpty(message = "{id.empty}", groups = {Default.class,New.class,Update.class})
    protected String id;

    /**
     * code/登录帐号
     */
    @ApiModelProperty(value = "code/登录帐号")
    @NotEmpty(message = "{itcode.empty}", groups = {Default.class,New.class,Update.class})
    protected String itcode;

    /**
     * 用户姓名
     */
    @ApiModelProperty(value = "用户姓名")
    @NotEmpty(message = "{name.empty}", groups = {Default.class,New.class,Update.class})
    protected String name;
}

--------------------------------controller类-------------------------------
@Api
@controller
public class UserController{
    @ApiOperation(value = "获取图书信息", notes = "获取图书信息", response = Book.class, responseContainer = "Item", produces = "application/json")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "book's name", required = true, dataType = "Long", paramType = "query"),
            @ApiImplicitParam(name = "date", value = "book's date", required = false, dataType = "string", paramType = "query")})
    @ApiResponses(value = { 
            @ApiResponse(code = 500, message = "2001:因输入数据问题导致的报错"),
            @ApiResponse(code = 500, message = "403:没有权限"),
            @ApiResponse(code = 500, message = "2500:通用报错（包括数据、逻辑、外键关联等，不区分错误类型）")})
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    @ResponseBody
    public Book getBook(@PathVariable Long id, String date) {
        return books.get(id);
    }
    
}

Swagger拓展皮肤

swagger皮肤拓展：

• 我们可以导入不同的包实现不同的皮肤定义
• 默认的：访问 http://localhost:8080/swagger-ui.html

<dependency>
   <groupId>io.springfoxgroupId>
   <artifactId>springfox-swagger-uiartifactId>
   <version>2.9.2version>
dependency>

• bootstrap-ui： 访问 http://localhost:8080/doc.html

<dependency>
   <groupId>com.github.xiaoymingroupId>
   <artifactId>swagger-bootstrap-uiartifactId>
   <version>1.9.1version>
dependency>

• Layui-ui ： 访问 http://localhost:8080/docs.html

<dependency>
   <groupId>com.github.caspar-chengroupId>
   <artifactId>swagger-ui-layerartifactId>
   <version>1.1.3version>
dependency>

• mg-ui ： 访问 http://localhost:8080/document.html

<dependency>
   <groupId>com.zyplayergroupId>
   <artifactId>swagger-mg-uiartifactId>
   <version>1.0.6version>
dependency>

Knife4j简介

Knife4j介绍：

• knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案（在非Java项目中也提供了前端UI的增强解决方案），前身是swagger-bootstrap-ui,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!
• 功能特性：
  ①简洁：基于左右菜单式的布局方式,是更符合国人的操作习惯吧.文档更清晰…
  ②个性化配置：个性化配置项,支持接口地址、接口description属性、UI增强等个性化配置功能…
  ③增强接口排序、Swagger资源保护、导出Markdown、参数缓存众多强大功能…

功能预览：

• 在线预览：http://knife4j.xiaominfo.com/doc.html
• 选择不同接口
• Authorize
• swagger实体：包含了swagger实体的相关信息
• swagger全局设置：全局参数设置
• 离线文档导出：Knife4j提供导出4种格式的离线文档(Html\Markdown\Word\Pdf)
• 个性化设置
• api文档
• 搜索功能

使用简介：

• 目前主要的模块包括：模块名称说明：
  ①knife4j为Java MVC框架集成Swagger的增强解决方案
  ②knife4j-admin云端Swagger接口文档注册管理中心,集成gateway网关对任意微服务文档进行组合集成
  ③knife4j-extensionchrome浏览器的增强swagger接口文档ui,快速渲染swagger资源
  ④knife4j-service为swagger服务的一系列接口服务程序
  ⑤knife4j-front knife4j-spring-ui的纯前端静态版本,用于集成非Java语言使用swagger-bootstrap-uiknife4j的前身,最后发布版本是1.9.6
• 单纯皮肤增强：
  ①不使用增强功能,纯粹换一个swagger的前端皮肤，这种情况是最简单的,你项目结构下无需变更
  ②可以直接引用swagger-bootstrap-ui的最后一个版本1.9.6或者使用knife4j-spring-ui

---老版本引用------
<dependency>
  <groupId>com.github.xiaoymingroupId>
  <artifactId>swagger-bootstrap-uiartifactId>
  <version>1.9.6version>
dependency>

------新版本引用-----
<dependency>
  <groupId>com.github.xiaoymingroupId>
  <artifactId>knife4j-spring-uiartifactId>
  <version>${lastVersion}version>
dependency>

• Spring Boot项目单体架构使用增强功能：
  ①在Spring Boot单体架构下,knife4j提供了starter供开发者快速使用。
  ②该包会引用所有的knife4j提供的资源，包括前端Ui的jar包。

<dependency>
  <groupId>com.github.xiaoymingroupId>
  <artifactId>knife4j-spring-boot-starterartifactId>
  <version>${knife4j.version}version>
dependency>

• Spring Cloud微服务架构：在Spring Cloud的微服务架构下,每个微服务其实并不需要引入前端的Ui资源,因此在每个微服务的Spring Boot项目下,引入knife4j提供的微服务starter。

<dependency>
  <groupId>com.github.xiaoymingroupId>
  <artifactId>knife4j-micro-spring-boot-starterartifactId>
  <version>${knife4j.version}version>
dependency>


---------在网关聚合文档服务下,可以再把前端的ui资源引入------------
<dependency>
   <groupId>com.github.xiaoymingroupId>
   <artifactId>knife4j-spring-boot-starterartifactId>
   <version>${knife4j.version}version>
dependency>

总结：

• 针对knife4j的总结，无非就是牛逼来形容，切实的解决了swaggerui不够友好的问题，而且还可以集成到其他语言的api项目中。

OpenAPI简介

OpenAPI 是什么?

• Open API 即开放 API，也称开放平台。 所谓的开放API（OpenAPI）是服务型网站常见的一种应用，网站的服务商将自己的网站服务封装成一系列 API（Application Programming Interface，应用编程接口）开放出去，供第三方开发者使用，这种行为就叫做开放网站的 API，所开放的 API就被称作 OpenAPI（开放 API ）。
• Swagger2已经在17年停止维护了，取而代之的是 Swagger3（基于OpenApi3）。

RESTful API 是什么?

• Representational State Transfer，翻译是”表现层状态转化”。可以总结为一句话：REST 是所有 Web应用都应该遵守的架构设计指导原则。
• 面向资源是 REST最明显的特征，对于同一个资源的一组不同的操作。资源是服务器上一个可命名的抽象概念，资源是以名词为核心来组织的，首先关注的是名词。REST要求，必须通过统一的接口来对资源执行各种操作。对于每个资源只能执行一组有限的操作。
• 符合 REST 设计标准的 API，即 RESTful API。REST 架构设计，遵循的各项标准和准则，就是 HTTP协议的表现，换句话说，HTTP 协议就是属于 REST 架构的设计模式。比如，无状态，请求-响应。

Swagger 是什么?

• Swagger™ 的目标是为 REST APIs定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger 定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger 去掉了调用服务时的很多猜测。
• 举个例子：
  ①现在的互联网充满了一个又一个信息孤岛和大量的碎片化的数据，用户想知道一些资讯，必须在不同的网站上跑来跑去.比如看电影，首先去google map查看周围的电影院，然后去大众点评网查看对这家电影院的评论，然后去电影院的网站上看看今天有什么电影上映。然后支付网站进行电子购票.整个过程非常繁琐，数据之间没有关联.充斥着大量的异构系统.
  ②为了解决这些问题.我们引入了openapi的概念.通过openapi,数据提供商开放了自己的数据，通过mashup将信息孤岛连接起来.整合这些信息碎片.
  ③如果google,大众点评网，电影院，支付宝均开放自己的openapi.然后有一个mashup程序将他们整合起来.那么用户就能体验一站式购物.进这个网站，找到电影院，查看电影院评价，如果评价好，查看电影院上映什么节目。电子订票.然后就能直接杀过去了。省时省力 。

四类api ：

• 同步服务api: 普通的Http无状态单次请求和响应
• 异步服务api: 应用于服务提供商提供的服务无法在当时处理完毕，先返回一个请求响应，当服务处理结束以后再将服务处理结果返回给服务调用者
• 订阅服务api: 类似rss.服务调用者只需要订阅服务即可获得服务提供商推送的服务内容
• 大数据量上传api: 上传文件

什么是oauth?

• OAuth协议致力于使网站和应用程序（统称为消费方）能够在无须用户透露其认证证书的情况下，通过API访问某个web服务（统称为服务提供方）的受保护资源。更一般地说，OAuth为API认证提供了一个可自由实现且通用的方法。

什么是openid?

• OpenID 是一个以用户为中心的数字身份识别框架，它具有开放、分散、自由等特点

什么是Mashup?

• mashup是糅合，是当今网络上新出现的一种网络现象,将两种以上使用公共或者私有数据库的web应用，加在一起，形成一个整合应用。一般使用源应用的api接口，或者是一些rss输出（含atom）作为内容源，合并的web应用用什么技术，则没有什么限制。

OpenAPI规范：

• OpenAPI规范始于Swagger规范，经过Reverb Technologies和SmartBear等公司多年的发展，OpenAPI计划拥有该规范（捐赠之后），OpenAPI Initiative在GitHub上托管社区驱动的规范。
• 规范是一种与语言无关的格式，用于描述RESTful Web服务，应用程序可以解释生成的文件，这样才能生成代码、生成文档并根据其描述的服务创建模拟应用。

什么是API优先开发？

• 应用程序向云环境这一演变趋势为更好地集成服务和增加代码重用提供了机会，只要拥有一个接口，然后通过该接口，其他服务的应用程序就可以与你的应用程序进行交互，这是向其他人公开你的功能，但是，开发API却不应该是在开发后才公开功能。
• API文档应该是构建应用程序的基础，这个原则正是API-First(API优先)开发的全部内容，你需要设计和创建描述新服务与外部世界之间交互的文档，一旦建立了这些交互，就可以开发代码逻辑来支持这些交互。让我们来看看这种方法带来的好处。

API-First如何使您的组织受益？

• 当你的组织从API文档开始时，这允许团队在开发过程中更快地开始彼此交互。API文档是应用程序与使用它的人之间的合同。
• 内部开发可以在API合同背后进行，而不会干扰使用它的人的努力，计划使用你的应用程序的团队可以使用API​​规范来了解如何与你的应用程序进行交互，甚至在开发之前。他们还可以使用该文档创建用于测试其应用程序的虚拟服务。

OpenAPI文档的剖析：

• 该规范的当前版本是3.0.1版，并在OpenAPI GitHub存储库中进行了详细记录。但是，如果你像我一样，我更喜欢看一个规范的例子，而不是通过描述文档描述每个可能的部分的明确的技术细节。
• 让我们看一个描述服务API的简单API文档，它允许用户创建，修改，检索和删除用户首选项。您可以在SwaggerHub上完整地查看此API。
• OpenAPI文档有三个必需的部分或对象：
  ①openapi - OpenAPI规范版本的语义版本号
  ②info - 有关API的元数据
  ③paths - API的可用路径和操作
• 你可以根据需要包含其他对象。其他对象包括安全性，服务器，标签和组件。

SpringFox与SpringDoc

SpringFox：

• SpringFox是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。常常用于Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。截至2020年4月，都未支持 OpenAPI3 标准。
• 补充：2020.7.14 发布了 3.0 支持 OpenAPI3，github 发布记录 但官网对 3.0 版本相关文档未完善，还是只有swagger 2.0 相关的。 升级到 OpenAPI3（java 中 swagger1.x 对应 OpenAPI2、swagger2.x对应OpenAPI3）官方文档。

SpringDoc：

• SpringDoc也是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger3 集成到 Spring 中。 也是用来在Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。
• 该组织下的项目支持swagger页面Oauth2登录（Open API3的内容），相较SpringFox来说，它的支撑时间更长，无疑是更好的选择。但由于国内发展较慢，在国内不容易看到太多有用的文档，不过可以访问它的官网。它的使用了swagger3（OpenAPI3），但 swagger3 并未对 swagger2 的注解做兼容，不易迁移，也因此，名气并不如spring fox。