【Java学习笔记】 Swagger2 学习笔记以及具体用法

最新推荐文章于 2024-06-28 10:17:30 发布

Xcong_Zhu

最新推荐文章于 2024-06-28 10:17:30 发布

阅读量719

点赞数

分类专栏：学习笔记文章标签： java 学习开发语言

本文链接：https://blog.csdn.net/Xcong_Zhu/article/details/127917399

版权

学习笔记专栏收录该内容

75 篇文章 3 订阅

订阅专栏

Swagger

一、是什么？

1、简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

简单理解就是两个作用

用于生成API文档的一个框架
还能进行在线测试

关联：

官网：https://swagger.io/

2、工具组件

有很多，记住一个核心常用组件

Swagger UI：会读取代码中的注释，生成API文档网页

二、优势

支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
- API文档也支持权限验证（观察者需要输入密码
- 不同的接口也有颜色分类（比如删除接口可以用红色
提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

三、文档界面的用法

1、支持很完整的备注

2、支持接口测试

可以测试响应的内容

四、springfox

功能和Swagger一样，也是可以根据代码生成接口文档，只需要正常的进行更新项目版本、修改代码即可、不需要收到修改描述文件

利用自身AOP的特性，集成了Swagger，低层还是Swagger，但是使用起来很方便。

在实际开发中，使用spring-fox + swagger

具体用法

一、极速上手

进入mvnrepository.com搜索对应的依赖[SpringFox Swagger2]

使用2.92版本的依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

导入另一个依赖[SpringFox Swagger UI]

也是2.92版本

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

在springboot启动类上方加入注解@EnableSwagger2 。即可启动测试
- 是Springfox提供的一个注解，代表swagger2相关技术的启动
- 会扫描启动类包及子包下所有类型的注解。做swagger文档的定值。
进入对应的地址即可访问http://localhost:端口号/swagger-ui.html
可以发现在没有写任何注解情况下，spirngfox已经自动帮我们识别了之前写好的controller。如下
网址预览

测试问题：这里出现一个bug提示

提示内容：Failed to start bean ‘documentationPluginsBootstrapper’

解决方法参考[http://t.csdn.cn/OHYMY]，原因就是是springboot的版本更新，导致的swagger2的异常

目前采用博客的第一个方法即解决——

在yml中新增配置

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

补充知识点。Springmvc对不同请求的分类

之前我们使用的请求方式，都是使用注解@RequestMapping。但是它只是其中一种请求方式，

@RequestMapping属于“无限制请求”
@PostMapping ——“POST请求”
@GetMapping——“get请求”

因为发现swagger也会识别这个请求类型做出不同的API文档，所以补充一下这个小知识点

二、具体配置用法（Swagger UI

在极速上手演示的，不难发现，默认Swagger就会读取一些springmvc的注解进行生成。如果有对应的约束（如POST/GET），就会有变化。

1、配置文档的标题内容

创建一个配置类（创建config包下，新建类如下

package com.cykj.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfiguration {
    /*
    创建了Docket类型的对象，并使用spring容器管理
    是swagger的全局配置
     */
    @Bean
    public Docket docket(){
        // 选择swagger版本
        Docket docket = new Docket(DocumentationType.SWAGGER_2);

        ApiInfo apiInfo = new ApiInfoBuilder()
                .contact(   // 配置swagger文档的主体
                        new Contact("发布者：朱华聪",  // 发布者信息
                                "http://www.ta.com",    // 发布者的企业网址
                                "zhc_yes@126.com")      // 发布者的电子邮件
                )
                .title("商品管理Swagger帮助文档测试")
                .description("描述测试描述测试描述测试描述测试描述测试描述测试")
                .version("1.3")
                .build();
        docket.apiInfo(apiInfo);
        return docket;
    }
}

如上配置后，效果如下图

2、扫描包配置

在原有的配置类内再加如下语句：

// 配置要扫描包的位置，默认是启动类所在包及所有子包
docket.select()
    // 配置要扫描的包，包括其子包
    .apis(RequestHandlerSelectors.basePackage("com.cykj.demo.controller"));

在此基础上，教程还讲解了使用自定义注解，跳过某些方法

三、Swagger2内置的常用注解

1、`@Api`：描述类

描述当前类型生成帮助文档的信息

tags —— 定义这个类的别名，可以使用大括号加逗号隔开的方式写多个别名

举个例子

@RequestMapping
@Api(tags = {"用户管理接口1","用户管理的接口别名~~"})
public class UserController {

效果如下

~~description~~ —— 描述信息，但是已经过时了

2、`@ApiOperation`——描述方法

value——必须的，这个方法的别名
notes——一些细节描述

举个例子

@ApiOperation(value = "登陆接口",notes = "我是描述我是描述我是描述我是描述我是描述我是描述")
    public ResponseVo login(String user , String pwd){

效果如下

3、`@ApiParam`主要描述方法参数

name——别名
value——具体描述
required —— 是否是必须的**（默认为false**

举个例子

public ResponseVo login(
    @ApiParam(name = "用户名",value = "必须要输入的",required = true) String user ,
    @ApiParam(name = "密码",value = "假设不必须") String pwd){

效果如下

4、@ApiIgnore 注解后不生成文档

顾名思义，添加后这个类/方法/属性不会再帮助文档里出现

5、`@ApiImplicitParam` 注解方法参数

和@apiparam的作用一样，不同的是这个注解是加在方法上面的

参数一样是name是别名，value是描述，也有required是否必须，三种参数组成

而且警告测试，两个注解不能共存，会出现如下bug

6、`@ApiModel` 描述数据类型

专门对实体类进行描述，这个实体类型，如果成为某个方法的返回值类型时，此注解将被解析。

举个例子

@ApiModel(value = "响应载体" , description = "用于响应用于响应用于响应用于响应")
public class ResponseVo {
    @ApiModelProperty(value = "表示状态" , name = "状态码" ,example = "200",required = true)
    private int code;   // 状态码
    @ApiModelProperty(value = "表示信息" , name = "提示信息" ,example = "success")
    private String message;     // 提示信息
    @ApiModelProperty(value = "存储数据" , name = "数据" ,example = "[m,n,b]")
    private Object data;    //数据