swagger是什么（十六）

前言：

swagger：神气十足，大摇大摆

在用Springboot进行开发时，有的实体类上用到了注解@ApiModelProperty("接受人代码")，特此整理此注解的出处及作用。

说白了，swagger就是为了方便系统生成API文档。而ApiModel与ApiModelProperty都是swagger的注解。

一、swagger是什么

1、是一款让你更好的书写API文档的规范且完整框架。
2、提供描述、生产、消费和可视化RESTful Web Service。
3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

参看swagger学习链接：https://www.e-learn.cn/content/qita/1542698

二、Swagger有什么用

swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础，对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、文档以及测试和部署，几乎支持所有语言）。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

三、SpringBoot 与 Swagger2

由于java的强大的注解功能,我们使用SpringBoot来结合Swagger2,在使用起来非常简单.
由于Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来。
Springfox的前身是swagger-springmvc，是一个开源的API doc框架，可以将我们的Controller的方法以文档的形式展现。
springfox大致原理:
springfox的大致原理就是，在项目启动的过程中，spring上下文在初始化的过程，框架自动根据配置加载一些swagger相关的bean到当前的上下文中，并自动扫描系统中可能需要生成api文档那些类，并生成相应的信息缓存起来。如果项目MVC控制层用的是springMvc那么会自动扫描所有Controller类，并生成对应的文档描述数据。该数据是json格式，通过路径：项目地址/ v2/api-docs可以访问到该数据，然后swaggerUI根据这份数据生成相应的文档描述界面。因为我们能拿到这份数据，所以我们也可以生成自己的页面.

参看链接：

https://blog.csdn.net/jamieblue1/article/details/99847744

https://blog.csdn.net/weixin_37509652/article/details/80094370

四、重新认识Swagger与springfox

做过Java后端开发的同学应该都用使用过Springfox和Swagger，但我相信很多同学都对这两个工具的理解和使用都有问题。

4.1 Swagger是什么

根据官网的介绍，Swagger是一系列用于Restful API开发的工具，开源的部分包括：

OpenAPI Specification：API规范，规定了如何描述一个系统的API
Swagger Codegen：用于通过API规范生成服务端和客户端代码
Swagger Editor：用来编写API规范
Swagger UI：用于展示API规范

非开源的部分包括：

Swagger Hub：云服务，相当于Editor + Codegen + UI
Swagger Inspector：手动测试API的工具
SoapUI Pro：功能测试和安全测试的自动化工具
LoadUI Pro：压力测试和性能测试的自动化工具

4.2 Springfox是什么

在大量的中文教程中，Springfox以这样的方式出现

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>

第二个看起来应该是springfox封装/修改的Swagger UI，第一个应该就是Springfox本体了，但为什么artifact有个swagger2的后缀？

这就要从Springfox是什么说起了。Springfox其实是一个通过扫描代码提取代码中的信息，生成API文档的工具。API文档的格式不止Swagger的OpenAPI Specification，还有RAML，jsonapi，Springfox的目标同样包括支持这些格式。这就能解释那个swagger2的后缀了，这只是Springfox对Swagger的支持。

在Swagger的教程中，都会提到@Api、@ApiModel、@ApiOperation这些注解，这些注解其实不是Springfox的，而是Swagger的。springfox-swagger2这个包依赖了swagger-core这个包，而这些注解正是在这里面。但是，swagger-core这个包是只支持JAX-RS2的，并不支持常用的Spring MVC。这就是springfox-swagger的作用了，它将上面那些用于JAX-RS2的注解适配到了Spring MVC上。

除了Spring MVC外，Springfox还支持如下库

Spring Data REST
JSR 303，这项标准的参考实现是Hibernate Validator

4.3 Swagger注解的滥用

在代码中的注解已经存储了大量的信息，如果再用swagger-core的注解将这些信息用另一种方式表达出来，很容易造成改了这里忘了改那里，即修改不同步。因此Springfox的开发者不推荐大家使用swagger-core的注解来描述API，认为swagger-core的注解只是补充，只能用于实现其他方法都不能实现的调整或者覆盖。例如，更应该使用Jackson的注解，而不是@ApiModelProperty；更应该使用@NotNull或者@RequestParam#required，而不是在文档里写一句此字段必填。

但是，springfox的开发者忽略了一个事实，中文开发者用swagger-core的注解更多的是用来添加中文描述，所以，该用的时候还是用吧。

参看链接：https://www.cnblogs.com/jason1990/p/12581773.html

五、@ApiModel和@ApiModelProperty用法

5.1@ApiModel

使用场景：在实体类上边使用，标记类是swagger的解析类。
概述：提供有关swagger模型的其它信息，类将在操作中用作类型时自动内省。
用法：
在这里插入图片描述

5.2 @ApiModelProperty

使用场景：使用在被 @ApiModel 注解的模型类的属性上。表示对model属性的说明或者数据操作更改。
概述：添加和操作模型属性的数据。
用法：
在这里插入图片描述

@ApiModel(value="user对象",description="用户对象user")
public class User implements Serializable{
    private static final long serialVersionUID = 1L;
     @ApiModelProperty(value="用户名",name="username",example="xingguo")
     private String username;
     @ApiModelProperty(value="状态",name="state",required=true)
      private Integer state;
      private String password;
      private String nickName;
      private Integer isDeleted;

      @ApiModelProperty(value="id数组",hidden=true)
      private String[] ids;
      private List<String> idList;
     //省略get/set
}

View Code

参看链接：

https://blog.csdn.net/weixin_39189376/article/details/97926012

https://www.cnblogs.com/huanghuanghui/p/9086860.html