springboot 集成 Swagger2（速通）

最新推荐文章于 2024-04-11 09:46:18 发布
最新推荐文章于 2024-04-11 09:46:18 发布
阅读量2.8k 收藏 6
点赞数 2
分类专栏： Spring Boot 文章标签： spring boot swagger2
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/m0_54355172/article/details/130839916
版权

目录

1. 概述

简单理解——代写接口文档的框架，可跟随接口修改实时更新。

Open API 格式：REST API 的描述格式，可使用 YAML 或 JSON 格式来编写。Open API 的描述范围：

  • 每个访问地址的类型；
  • 每个操作的参数；
  • 认证方法；
  • 连接信息、声明，使用团队和其他信息。

Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API。将相关信息通过 YAML/JSON 格式存储在描述文件中，再通过描述文件去更新接口文档。其工具组包：

  • Swagger Editor：基于浏览器编辑器，可以编写 Open API 规范；
  • Swagger UI：将 Open API 规范呈现为交互式 API 文档，即描述文件（常用）；
  • Swagger Codegen：将描述文件生成 HTML 和 cwiki 形式的接口文档，可同时生成多种语言的客户端和服务端代码；
  • Swagger Inspector：类似 Swagger UI，但包含更多信息，比如请求的实际参数数据；
  • Swagger Hub：集成上面工具的所有功能，上传描述文件到 Hub ，就可以完成上面工具的所有工作。

Springfox：Swagger 在遇到版本迭代的时候还需要更改描述文件，但 Springfox 则优化了此过程，会根据代码实时生成文档。通过注解的方式将 Swagger 集成在代码中。

2. 案例 1

依赖：

  • web 项目

            <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

  • springfox 依赖，要一次性导入下面两个，版本要对应

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

注解：

  • 启动类注解：

    @EnableSwagger2         // 开启 swagger2 相关技术，扫描当前类所在包及其子包中的注解 
@SpringBootApplication

  • 控制类：

    @RestController
public class SwaggerController {
    @GetMapping("/get")
    public String getStr(String str) {
        return "SELECT " + str;
    }

    @PostMapping("/post")
    public String postStr(String str) {
        return "CREATE " + str;
    }

    @PutMapping("/put")
    public String putStr(String str) {
        return "UPDATE " + str;
    }

    @PatchMapping("/patch")
    public String patchStr(String str) {
        return "UPDATE " + str;
    }
    
    @DeleteMapping("/delete")
    public String deleteStr(String str) {
        return "DELETE " + str;
    }
}

  • 运行代码，访问 http://127.0.0.1:8080/swagger-ui.html，这里可能会遇到以下的报错：

    启动项目遇到报错：java: 警告: 源发行版 17 需要目标发行版 17
    解决方案：https://blog.csdn.net/weixin_44299027/article/details/120848738


    启动项目遇到报错：类文件具有错误的版本 61.0, 应为 52.0
    解决方案：spring6.0 开始 jdk 要求17以上才行，要么升级 JDK，要么降低 spring 版本。
    我选择降低 spring 版本：

    • https://mvnrepository.com/ 查看 spring-boot-starter-parent 的版本号
    • 选择 3 以下的版本号，修改 Maven 依赖 spring-boot-starter-parent


    启动项目遇到报错：Failed to start bean ‘documentationPluginsBootstrapper’;
    解决方案：springboot 升级到 2.6.0之后，swagger版本和springboot出现了不兼容情况，要么降低 springboot 版本，要么配置 spring.mvc.pathmatch.matching-strategy=ant_path_matcher

    • A.降低 springboot 版本不再做赘述（可降低至 2.5 以下就绝对没问题）；
    • B.配置1：① 启动类加上注解 @EnableWebMvc；② 配置文件加上 spring.mvc.pathmatch.matching-strategy=ant_path_matcher;
    • C.配置1不生效情况：参考：https://blog.csdn.net/weixin_39792935/article/details/122215625
    • D.当上述三种解决方案都不生效的情况下，我采用的终极解决方案：降低 Springboot 版本（2.5.6），并采用 C 方案的配置，然后访问 http://127.0.0.1:8080/swagger-ui.html

      访问页面为空：

      解决方案：启动类加上注解@EnableOpenApi ，并访问 http://localhost:8080/swagger-ui/index.html

  • 解决无法访问的问题：

    • 修改配置文件 application.properties

      spring.mvc.pathmatch.matching-strategy=ant_path_matcher

    • 新增配置类：

      package com.chenjy.swagger.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

/**
 * @Desc 解决高版本无法兼容 swagger2 的问题
 *       如此配置之后，就可通过 http://127.0.0.1:8080/doc.html 去访问 swagger-ui.html
 */
@Configuration
public class WebMvcConfigurer extends WebMvcConfigurationSupport {

    /**
     * 发现如果继承了WebMvcConfigurationSupport，则在yml中配置的相关内容会失效。 需要重新指定静态资源
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations(
                "classpath:/static/");
        registry.addResourceHandler("swagger-ui.html", "doc.html").addResourceLocations(
                "classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations(
                "classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }

}

    • 降低 springboot 版本到 2.5.6

          <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.5.6</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

  • 访问界面如下图，可以从中看到我们写的接口：

3. UI 的简单使用

扫描项目中（启动类同级目录及其子目录中）的所有控制器（默认是控制器） 中的 @GetMapping/@RequestMapping(method = {RequestMethod.GET}) 系列的注解，然后去解析注解对应的映射地址以及注解约束的请求方式（GET、POST、DELET…，默认为 GET）。点击具体方法可看详细的请求信息：

可点击 Try it out 测试一下：

4. 简单配置 Docket 对象

1. 配置文档的描述信息

package com.chenjy.swagger.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 SwaggerConfigurer {

    /**
     * @return Docket——Swagger 中的全局配置对象
     */
    @Bean
    public Docket docket() {
        // DocumentationType.SWAGGER_2 告诉 Springfox 当前的 Swagger 版本是 Swagger2
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        // API 帮助文档的描述信息
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("Swagger 文档")// 文档标题
                .description("Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API。")// 描述信息
                .version("1.0.1")// 版本号
                .contact(
                        // name url email
                        new Contact("364.99°的文档", // 文档发布者名称
                                "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
                                "2190826197@qq.com" // 文档发布者的邮箱
                        )
                )
                // 构建器模式
                .build();
        // 给 docket 上下文配置 API 描述信息
        docket.apiInfo(apiInfo);
        return docket;
    }
}

2. 定义包扫描规则

在 docket 方法中添加以下配置：

        docket
                .select() // 获取 docket 中的选择器，如：扫描哪个包的注解
                .apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger.controller")); // 定义规则——包扫描规则

5. 指定接口不生成文档

1. 自定义注解

→ 如何自定义一个注解 ←

定义一个注解，标注当前接口不需要生成 Swagger 文档：

package com.chenjy.swagger.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.METHOD, ElementType.TYPE}) // 此注解用于描述 方法、类
@Retention(RetentionPolicy.RUNTIME)// 注释信息会在运行时被有效
public @interface NoSwagger {
    // 自定义注解属性 @NoSwagger(value="")
    String value() default "";
}

配置类使注解规则生效：

package com.chenjy.swagger.config;

import com.chenjy.swagger.annotation.NoSwagger;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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 static com.google.common.base.Predicates.not;
import static springfox.documentation.builders.RequestHandlerSelectors.withMethodAnnotation;

@Configuration
public class SwaggerConfigurer {

    /**
     * @return Docket——Swagger 中的全局配置对象
     */
    @Bean
    public Docket docket() {
        // DocumentationType.SWAGGER_2 告诉 Springfox 当前的 Swagger 版本是 Swagger2
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        // API 帮助文档的描述信息
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("Swagger 文档")// 文档标题
                .description("Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API。")// 描述信息
                .version("1.0.1")// 版本号
                .contact(
                        // name url email
                        new Contact("364.99°的文档", // 文档发布者名称
                                "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
                                "2190826197@qq.com" // 文档发布者的邮箱
                        )
                )
                // 构建器模式
                .build();
        // 给 docket 上下文配置 API 描述信息
        docket.apiInfo(apiInfo);
        Docket build = docket
                .select() // 获取 docket 中的选择器，如：扫描哪个包的注解
                .apis(
                        not( // 取反
                                withMethodAnnotation(NoSwagger.class) // 当方法上有注解的时候返回 true
                        )
                )
                .apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger.controller")) // 定义规则——包扫描规则
                .build();
        return build;
    }
}

注意： 这里需要重新 build 一次 Docket ，然后返回重新 build 之后的 docket，否则不会生效。

标注在接口方法上：

    @NoSwagger
    @PatchMapping("/patch")
    public String patchStr(String str) {
        return "UPDATE " + str;
    }

重启项目，访问：

优化写法：

        Docket build = docket
                .select() // 获取 docket 中的选择器，如：扫描哪个包的注解
                .apis(
                        and(
                                not( // 取反
                                        withMethodAnnotation(NoSwagger.class) // 当方法上有注解的时候返回 true
                                ),
                                RequestHandlerSelectors.basePackage("com.chenjy.swagger.controller")
                        )
                )
                .build();
        return build;

注意：

  • and 和 not 都是 com.google.common.base.Predicates 中的静态方法；
  • withMethodAnnotation 是 springfox.documentation.builders.RequestHandlerSelectors 中的静态方法。

2. 路径匹配

springfox.documentation.builders.PathSelectors

只有路径前缀为 /test 的接口方法才会生成文档。

        Docket build = docket
                .select() // 获取 docket 中的选择器，如：扫描哪个包的注解
                .paths(
                        PathSelectors.regex("/test/.*") // 使用正则表达式  . 任意字符   * 0个或多个
                )
                .build();
        return build;

同时多种路径匹配规则： Predicates.or

                .paths(
                        Predicates.or(
                                PathSelectors.regex("/test/.*"),
                                PathSelectors.regex("/.*")
                        )
                )

→ 正则表达式语法 ←

6. 常用注解

@Api(tags = {"test 接口 API"})

  • 类注解，描述当前类型生成帮助文档的信息；
  • tags 定义控制器别名，可以有多个值，有几个别名，文档中就有几个控制器目录。

@ApiOperation(value = "get 方法，执行查询操作", notes = "一个小 demo")

  • 类、方法注解，常用来描述方法。

@ApiParam()

  • 参数、方法、属性注解，常用来描述参数；

    @PostMapping("/post")
public String postStr(
        @ApiParam(name = "字符串", value = "用来输出的字符串", required = true) String str,
        @ApiParam(name = "序列号", required = false) @RequestParam(defaultValue = "001", required = false)String num
) {
    return "CREATE " + str + num;
}

@ApiIgnore

  • 方法、属性注解，让此注解描述的方法或类型不生成 API 文档。

        @ApiIgnore
    @PutMapping("/put")
    public String putStr(String str) {
        return "UPDATE " + str;
    }

@ApiImplicitParam

  • 在方法上描述方法参数，只能描述一个参数。

        @ApiImplicitParam(
            name = "str", value = "一个字符串", required = true, paramType = "java.lang.String", dataType = "任意字符串"
    )
    @DeleteMapping("/delete")
    public String deleteStr(String str, Integer num) {
        return "DELETE " + str;
    }

ApiImplicitParams

  • 在方法上描述参数，可以描述多个参数。
        @ApiImplicitParams(value = {
           @ApiImplicitParam( name = "str", value = "一个字符串", required = true, paramType = "java.lang.String", dataType = "任意字符串" ),
           @ApiImplicitParam( name = "num", value = "一个整数") 
    })
    @DeleteMapping("/delete")
    public String deleteStr(String str, Integer num) {
        return "DELETE " + str;
    }

@ApiModel

  • 描述实体类，当此实体类被作为返回类型用于 API 帮助文档中的接口方法中，此注解被解析。

    @Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel( value = "一个实体类", description = "存储数据并返回")
public class TestDto {
    private String name;
    private Integer num;
}

        @PatchMapping("/patch")
    public TestDto patchStr(String str, Integer num) {
        return new TestDto(str, num);
    }

@ApiModelProperty

  • 描述实体类的属性，要搭配 @ApiModel 使用。

    @Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel( value = "一个实体类", description = "存储数据并返回")
public class TestDto {
    @ApiModelProperty( value = "姓名", example = "张三", hidden = false)
    private String name;
    @ApiModelProperty( value = "序列号")
    private Integer num;
}


注意：

  • GET：不能使用 @requestBody ；
  • POST：可以使用 @requestBody (对于参数转化的配置必须统一)和 @requestParam 。
364.99°
关注
  • 2
    点赞
  • 踩
  • 6
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论
专栏目录
SpringBoot整合Swagger2实例方法
08-25
SpringBoot 整合 Swagger2 实例方法 在软件开发中，编写接口文档是必不可少的一步，但是手写文档会带来很大的工作量，且如果接口有变更则需要频繁修改并且发给相关的人，无形中增加了工作量。为了解决这个问题，...
SpringBoot集成Swagger简单使用
12-22
SpringBoot集成Swagger简单使用
SpringBoot与Swagger2.0集成
Mr_chen的博客
11-21 463
SpringBoot与Swagger2.0集成 前言（异步执行的引入） 案例github地址（如果有用点个star呗） https://github.com/chenxiban/SpringBoot-Asyn.git 通常情况下，用户在对我们服务器发送请求获取结果时，其实并不关心我们服务器端是如何处理的，而只关 心是否能快速获取结果（例：比如我们在淘宝提交一个订单，这时我们只会关心订单有没有快...
Swagger2最完整的文档
qq18346342939的博客
11-08 9510
1、引入三个依赖，其中第三个是为了优化页面用； io.springfox springfox-swagger2 2.4.0 io.springfox springfox-swagger-ui 2.4.0 com.github.xiaoymin swagger-bootstrap-ui 1.6 2、编写配置类； p......
SpringBoot整合Swagger2 详解
最新发布
Java毕设项目分享
04-11 914
SpringBoot整合Swagger2 详解。
Swagger2 详解
共勉
06-28 947
传统意义上的文档都是后端开发人员手动编写的，相信大家也都知道这种方式很难保证文档的及时性，这种文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。这是由于实体类使用@ApiModelProperty时，example属性没有赋值导致的，在AbstractSerializableParameter的getExample方法中会将数值属性的example的转换数值类返回，example的默认值是""，因此当example没有赋值时，会出现上面的异常。作用于方法，用来忽略生成该方法的Api文档。
项目配置Swagger2生成API接口文档
shkstart的博客
10-28 1187
一、Swagger2介绍 前后端分离开发模式中，api文档是最好的沟通方式。 Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 及时性 (接口变更后，能够及时准确地通知相关前后端开发人员) 规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息) 一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧) 可测性 (直接在接口文档上进行测试，以方便理解业务) 二、配置Swagger2 1、创建common
springboot 集成 Swagger2 配置以及常用注解的说明和使用 （ 超详细）
m0_63180675的博客
06-30 5839
一、注解的使用 和 说明结构化说明如下： @Api：用在请求的类上，表示对类的说明 tags="说明该类的作用，可以在UI界面上看到的注解" （也就是给类取别名） value="该参数没什么意义，在UI界面上也看到，所以不需要配置" @ApiOperation：用在请求的方法上，说明方法的用途、作用 value="说明方法的用途、作用" notes="方法的备注说明" @ApiImplicitParams：用在请求的方法上，表示一组参数说明 @Ap
SpringBoot集成Swagger2
owl notes
04-21 143
以上就是SpringBoot集成swagger内容。需要注意的是，不同版本会导致swagger集成后网页访问报错，参数定义不一致也会有同样的问题。
springboot集成swagger过程解析
08-25
在@Spring Boot项目中，需要添加Swagger的依赖项，包括springfox-swagger2和springfox-swagger-ui。可以在pom.xml文件中添加以下依赖项： ```xml <groupId>io.springfox <artifactId>springfox-swagger2 ...
springboot集成swagger的demo
11-20
后端在写接口，经常会出现接口变更，往往维护一份好的时效性高的接口文档是一件非常繁琐的事情，所以这里给出一份Springboot集成swagger的demo来给大家参考
springboot集成swagger
09-16
swagger练习
Springboot 项目配置Swagger2
u011447403的专栏
08-21 348
swagger2 的简单配置方法
简谈swagger的注解说明
xudong的博客
08-30 293
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。 • @Api：修饰整个类，描述Controller的作用 • @ApiOperation：描述一个类的一个方法，或者说一个接口 • @ApiParam：单个参数描述 • @ApiModel：用对象来接收参数 • @ApiProperty：用对象接收参数时，描述对象的一个字段 • @ApiRespo...
SpringBoot项目中使用Swagger2，及其详细介绍注解
qq_45830276的博客
08-27 1722
编写和维护接口文档是每个程序员的职责，根据Swagger2可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。
springboot整合swagger2
m0_46487331的博客
06-08 1473
springboot整合swagger
Spring Boot——集成Swagger
一心同学的博客
12-31 3982
保姆级别讲解Swagger工具，讲解关于Swagger的各种实用知识点以及注意事项。
SpringBoot整合Swagger2
weixin_56109504的博客
10-22 306
SpringBoot整合Swagger2简明教程
springboot（八）集成Swaggger2
念念不忘，必有回响
12-20 610
文章目录Swagger2简介项目目录引入依赖application.yml建Swagger2配置类Swagger常用注解构建测试Controller测试项目源码 Swagger2简介 Swagger是一款可以快速生成符合RESTful风格API并进行在线调试的插件 项目目录 引入依赖 <!--Swagger-UI API文档生产工具--> <depende...
springboot整合swagger2 3.0.0
08-18
要实现springboot整合swagger2 3.0.0版本，你需要按照以下步骤操作： 1. 创建一个maven项目并引入spring-boot-starter-web和springfox-boot-starter依赖。在pom.xml文件中添加以下代码： ```xml <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <!-- <version>2.5.6</version> --> <!-- <version>2.6.3</version> --> <!-- <version>2.6.5</version> --> <version>2.7.3</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>1.18.26</version> </dependency> ``` 2. 在application.yml配置文件中添加以下内容： ```yaml spring: mvc: pathmatch: matching-strategy: ant_path_matcher ``` 3. 创建启动类，并在其中添加`@EnableSwagger2`注解。例如： ```java @SpringBootApplication @EnableSwagger2 public class YourApplication { public static void main(String[] args) { SpringApplication.run(YourApplication.class, args); } } ``` 这样就完成了springboot整合swagger2 3.0.0版本的配置。你可以根据需要在项目中编写相应的接口文档注解以及其他相关配置。如果需要更详细的操作步骤和示例代码，你可以参考中提供的链接。<span class="em">1</span><span class="em">2</span><span class="em">3</span> #### 引用[.reference_title] - *1* *2* [Springboot整合Swagger2（3.0.0版本）](https://blog.csdn.net/mo_sss/article/details/130820204)[target="_blank" data-report-click={"spm":"1018.2226.3001.9630","extra":{"utm_source":"vip_chatgpt_common_search_pc_result","utm_medium":"distribute.pc_search_result.none-task-cask-2~all~insert_cask~default-1-null.142^v93^chatsearchT3_2"}}] [.reference_item style="max-width: 50%"] - *3* [Springboot整合Swagger UI 3.0.0 版本](https://blog.csdn.net/qq_42102911/article/details/126410050)[target="_blank" data-report-click={"spm":"1018.2226.3001.9630","extra":{"utm_source":"vip_chatgpt_common_search_pc_result","utm_medium":"distribute.pc_search_result.none-task-cask-2~all~insert_cask~default-1-null.142^v93^chatsearchT3_2"}}] [.reference_item style="max-width: 50%"] [ .reference_list ]

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

364.99°

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值