Swagger相关图形

Bertha 。 2023-09-29 12:13 12阅读 0赞

## 一 生活需求：接口文档可以实时动态生成，前端最希望了 ##

## 二 解决方案：Swagger ##

### 1、思想 ###

1.  Open API规范，原名Swagger规范，是REST API的API描述格式。
    
    1.  Open API文件允许描述整个API，包括：
        
        1.  每个访问地址的类型。POST或GET。
        2.  每个操作的参数。包括输入输出参数。
        3.  认证方法。
        4.  连接信息，声明，使用团队和其他信息。
2.  OpenAPI =规范。Swagger =实现规范的工具。Swagger通过Open API文件，来生成接口文档，甚至可以提供端点方便各类人员通过浏览器去访问接口文档。使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及**生成各端代码****。**

### 2、结构 ###

Swagger工具包括的组件：

1.  Swagger Editor：类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览
    
    描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
2.  Swagger UI：提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
3.  Swagger Codegen：通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
4.  Swagger Inspector：感觉和postman差不多，可以理解为一个可以对接口进行测试的在线版的postman。又感觉和Swagger UI有点类似，比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
5.  Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

### 3、案例：极致使用 ###

1.  编写SpringBoot项目
2.  导入Spring-fox依赖
3.  添加注解
    
    1.  @EnableSwagger2：表示对当前项目中全部控制器进行扫描，应用Swagger2。
4.  访问swagger-ui
    
    1.  http://ip:port/swagger-ui.html即可以访问到swagger-ui页面。
    2.  在swagger-ui页面中可以可视化的进行操作项目中所有接口。

### 4、Swagger配置：SwaggerConfig.java ###

我们要修改 API 信息默认配置的话，可以通过新建一个 com.java1234.config.SwaggerConfig.java 配置类，重写 ApiInfo  实现，以及重写  Docket  实现并且设置 apiInfo ；

1.  配置基本信息
2.  设置扫描的包
3.  自定义注解设置不需要生成接口文档的方法
4.  设置范围
5.  配置Swagger开关
6.  配置API分组
7.  实体配置

### 5、常用注解 ###

1.  @Api类上。控制整个类生成接口信息的内容。
    
    1.  tags="说明该类的作用，可以在UI界面上看到的注解" 
    2.  value="该参数没什么意义，在 UI 界面上也看到，所以不需要配置 " 
2.  @ApiModel类上，主要应用Model，也就是说这个注解一般都是写在实体类上。
    
    用于响应类上，表示一个返回响应数据的信息 
    
    （这种一般用在 post 创建的时候，使用 @RequestBody 这样的场景， 
    
    请求参数无法使用 @ApiImplicitParam 注解进行描述的时候）
3.  @ApiOperation方法上，对方法进行总体描述
    
    1.  value="说明方法的用途、作用" 
    2.  notes="方法的备注说明 " 
4.  @ApiParam方法参数前面。用于对参数进行描述或说明是否为必添项等说明。
5.  @ApiImplicitParam方法上，表示单独的请求参数，总体功能和@ApiParam类似。
    
    @ApiImplicitParams：用在请求的方法上，表示一组参数说明   
     @ApiImplicitParam：用在 @ApiImplicitParams注解中，指定一个请求参数的各个方面   
    name：参数名  
    value：参数的汉字说明、解释  
    required：参数是否必须传   
    paramType：参数放在哪个地方   
    · header --> 请求参数的获取：@RequestHeader   
    · query --> 请求参数的获取：@RequestParam   
    · path（用于restful接口）\--> 请求参数的获取：@PathVariable   
    · div（不常用）   
    · form（不常用）   
    dataType：参数类型，默认String，其它值dataType="Integer"   
    defaultValue：参数的默认值 
6.  @ApiModelProperty方法或属性上。用于当对象作为参数时定义这个字段的内容。描述响应类的属性 
7.  @ApiIgnore方法或类或参数上，表示这个方法或类被忽略。
8.  @ApiResponses：用在请求的方法上，表示一组响应 
    
     @ApiResponse ：用在 @ApiResponses 中，一般用于表达一个错误的响应信息 
    
     code：数字，例如400 
    
     message：信息，例如" 请求参数没填好 " 
    
     response：抛出异常的类

1.  ## 三 Springfox VS Swagger ##
    
    1.   Spring-fox利用自身AOP特性，把Swagger集成进来，底层还是Swagger。其中springfox-swagger2是swagger核心内容的封装，springfox-swagger-ui是对swagger-ui的封装。所以在实际开发中，都是直接使用spring-fox。

## **四 Swagger-UI使用**  ##

1.  查询
    
    1.  看到所有需要生成接口文档的控制器名称。
    2.  接口对应的文档
2.  调试与测试
    
    1.  说明：很多时候，前后端分离，传的是json，键值对，用swagger-ui提供的简陋接口测试工具很难用， 所以接口测试我们还是用专业的 **postman**

## 五 参考 ##

[狂神说SpringBoot14：集成Swagger终极版][SpringBoot14_Swagger]

[【狂神说Java】一小时掌握Swagger技术\_哔哩哔哩\_bilibili][Java_Swagger_bilibili]

[Swagger2最完整的文档\_修心光的博客-CSDN博客\_swagger官方文档][Swagger2_-CSDN_swagger]

[【Swagger】1\_Spring Boot 中搭建 Swagger\_Code\_27的博客-CSDN博客][Swagger_1_Spring Boot _ Swagger_Code_27_-CSDN]

[swagger教程、Swagger视频教程\_飞飞不 会飞的博客-CSDN博客\_swagger教程][swagger_Swagger_ _-CSDN_swagger]

[SpringBoot14_Swagger]: https://mp.weixin.qq.com/s/0-c0MAgtyOeKx6qzmdUG0w
[Java_Swagger_bilibili]: https://www.bilibili.com/video/BV1Y441197Lw?spm_id_from=333.337.search-card.all.click
[Swagger2_-CSDN_swagger]: https://blog.csdn.net/qq18346342939/article/details/102979819
[Swagger_1_Spring Boot _ Swagger_Code_27_-CSDN]: https://blog.csdn.net/XJ0927/article/details/109704313
[swagger_Swagger_ _-CSDN_swagger]: https://blog.csdn.net/qq122516902/article/details/89417964