springboot 集成 Swagger3(速通)

这篇具有很好参考价值的文章主要介绍了springboot 集成 Swagger3(速通)。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

→ springboot 集成 Swagger2 ←

1. 案例

这次直接使用 2.5.6 的 spring-boot 。

  1. 依赖:

        <parent>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-parent</artifactId>
            <version>2.5.6</version>
            <relativePath/> <!-- lookup parent from repository -->
        </parent>
    
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>
            <!--swagger3-->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-boot-starter</artifactId>
                <version>3.0.0</version>
            </dependency>
            
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <optional>true</optional>
            </dependency>
        </dependencies>
    
  2. 启动类加注解 @EnableOpenApi

  3. 新建测试类

    @RestController
    @RequestMapping("/test")
    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;
        }
    
        @NoSwagger
        @PatchMapping("/patch")
        public String patchStr(String str) {
            return "UPDATE " + str;
        }
    
        @DeleteMapping("/delete")
        public String deleteStr(String str) {
            return "DELETE " + str;
        }
    }
    
  4. 访问 http://127.0.0.1:8080/swagger-ui.html ,没错,又是 Error 页面
    springboot swagger3,Spring Boot,spring boot,swagger

此部分参考:https://blog.csdn.net/mmmm0584/article/details/117786055


在swagger3.0中,swagger-ui.html的位置发生了变化:
springboot swagger3,Spring Boot,spring boot,swagger    springboot swagger3,Spring Boot,spring boot,swagger
所以路径也变了:http://127.0.0.1:8080/swagger-ui.htmlhttp://127.0.0.1:8080/swagger-ui/index.html

  1. 访问 http://127.0.0.1:8080/swagger-ui/index.html
    springboot swagger3,Spring Boot,spring boot,swagger

2. info 配置

新建一个配置类:

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.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.HashSet;

@Configuration
public class Swagger3Conf {
    @Bean
    public Docket createDocket() {
        return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本号
                .apiInfo(createApiInfo());
    }

    @Bean
    public ApiInfo createApiInfo() {
//        // 写法一
//        return new ApiInfoBuilder()
//                .title("Swagger3 文档案例")
//                .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();
        // 写法二
        return new ApiInfo(
                "Swagger3 文档案例",
                "Swagger :一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。",
                "1.0.1",
                "https://blog.csdn.net/m0_54355172",
                new Contact("364.99°的文档", // 文档发布者名称
                                "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
                                "2190826197@qq.com" // 文档发布者的邮箱
                        ),
                "364.99°",
                "https://blog.csdn.net/m0_54355172",
                new HashSet<>());
        }
}

springboot swagger3,Spring Boot,spring boot,swagger

  • Docket Swagger 的实例,可通过 Docket 对象来配置 Swagger;
  • ApiInfo 文件描述的配置对象。

3. Docket 配置

1. 开关配置

    @Bean
    public Docket createDocket() {
        return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本号
                .enable(false)// 关闭文档
                .apiInfo(createApiInfo());
    }

springboot swagger3,Spring Boot,spring boot,swagger

注意: 一般只有在测试环境才会用到 Swagger,在生产环境中会把它关闭掉,为了安全与效率。

2. 扫描路径

                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger2.controller"))
                .build()

springboot swagger3,Spring Boot,spring boot,swagger

3. 路径匹配

新建一个控制器:

@Api(tags = "other 接口 API")
@RestController
@RequestMapping("/other")
public class OtherController {
    @GetMapping("getInfo")
    public String getInfo() {
        return "information";
    }
}
                .select()
                .paths(PathSelectors.ant("/other/**"))
                .build()

springboot swagger3,Spring Boot,spring boot,swagger

4. 分组管理

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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 java.util.HashSet;

@Configuration
public class Swagger3Conf {
    @Bean
    public Docket createDocket01() {
        return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本号
                .groupName("other 组")
                .enable(true)// 关闭文档
                .select()
                .paths(PathSelectors.ant("/other/**"))
                .build()
                .apiInfo(createApiInfo());
    }

	@Bean
    public Docket createDocket02() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("test 组")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger2.controller"))
                .build()
                .apiInfo(
                        new ApiInfoBuilder()
                                .title("Swagger3 文档案例")
                                .build()
                );
    }

    @Bean
    public ApiInfo createApiInfo() {
//        // 写法一
//        return new ApiInfoBuilder()
//                .title("Swagger3 文档案例")
//                .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();
        // 写法二
        return new ApiInfo(
                "Swagger3 文档案例",
                "Swagger :一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。",
                "1.0.1",
                "https://blog.csdn.net/m0_54355172",
                new Contact("364.99°的文档", // 文档发布者名称
                                "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
                                "2190826197@qq.com" // 文档发布者的邮箱
                        ),
                "364.99°",
                "https://blog.csdn.net/m0_54355172",
                new HashSet<>());
        }
}

springboot swagger3,Spring Boot,spring boot,swagger

4. 常用注解

1. 说明

和 Swagger2 一样,其常用注解还是如下几个:文章来源地址https://www.toymoban.com/news/detail-770160.html

常用注解 注解说明 常用属性 属性说明
@Api 类注解,常用来给文档中的控制器取别名 tags 别名
@ApiOperation 方法/类注解,常用来描述方法 value
notes
方法说明
方法备注
@ApiParam 参数/方法/属性注解,常用来描述参数 name
value
required
参数名
补充描述
是否必须
@ApiIgnore 方法/属性注解,使被标注方法不生成文档 - -
@ApiImplicitParam 方法注解,描述一个参数 name
value
name
required
paramType
dataType
defaultValue
参数名
补充说明

是否必传
参数位置(header、query、path)
参数类型(默认 String)
默认值
@ApiImplicitParams 搭配 @ApiImplicitParam 一起使用,描述一组参数 springboot swagger3,Spring Boot,spring boot,swagger
@ApiResponse 方法注解,表达一个错误的响应信息 code
message
response
整型
字符串
异常信息(默认 String 类型)
@ApiResponses 搭配 @ApiResponse 一起使用,参考 @ApiImplicitParams
@ApiModel 类注解,当此实体类被作为返回类型用于 API 帮助文档中的接口方法中,此注解被解析 value
description
实体类名
补充描述
@ApiModelProperty 属性注解,搭配 @ApiModel 使用 value
example
hidden
属性名
示例
是否隐藏

2. 案例

import com.chenjy.swagger2.dto.TestDto;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

@Api(tags = {"test 接口 API"})
@RestController
public class SwaggerController {

    @ApiResponses({
            @ApiResponse(code = 1, message = "查询成功"),
            @ApiResponse(code = -1, message = "查询失败")
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "角色名", required = false, defaultValue = "张三"),
            @ApiImplicitParam(name = "num", value = "序列号", required = true)
    }
    )
    @PostMapping("/getInfo")
    public TestDto getInfo(String name, Integer num) {
        return new TestDto(name, num);
    }
    
    @ApiIgnore
    @GetMapping("/getStr")
    public String getStr(String name) {
        return name;
    }
}
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel( value = "角色实体类", description = "存储数据并返回")
public class TestDto {
    @ApiModelProperty( value = "姓名", example = "张三", hidden = false)
    private String name;
    @ApiModelProperty( value = "序列号", example = "1")
    private Integer num;
}
springboot swagger3,Spring Boot,spring boot,swaggerspringboot swagger3,Spring Boot,spring boot,swaggerspringboot swagger3,Spring Boot,spring boot,swagger

到了这里,关于springboot 集成 Swagger3(速通)的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • 【Springboot系列】Springboot整合Swagger3不简单

       Swagger是一个根据代码注解生成接口文档的工具,减少和前端之间的沟通,前端同学看着文档就可以开发了,提升了效率,之前很少写swagger,这次自己动手写,还是有点麻烦,不怎么懂,记录下,避免下次继续踩坑         新建一个springboo项目,一路next就好,这里使用的

    2024年02月05日
    浏览(38)
  • swagger3 快速整合 springboot 2.6.15

    2024年02月11日
    浏览(37)
  • SpringBoot——2.7.3版本整合Swagger3

    Swagger2(基于openApi3)已经在17年停止维护了,取而代之的是 sagger3(基于openApi3),而国内几乎没有 sagger3使用的文档,百度搜出来的大部分都是swagger2的使用,这篇文章将介绍如何在 java 中使用 openApi3(swagger3)。 Open API OpenApi是业界真正的 api 文档标准,其是由 Swagger 来维护

    2024年02月11日
    浏览(36)
  • springboot配置swagger3-springfox实现

    springfox 之前配置需要声明多个依赖,到了 3 直接声明一个 starter 就行了. springboot 版本 2.7.7 springfox-boot-starter 版本 3.0.0 声明依赖 声明yml配置 bean配置

    2024年02月12日
    浏览(35)
  • SpringBoot3整合OpenAPI3(Swagger3)

    swagger2 更新到3后,再使用方法上发生了很大的变化,名称也变为 OpenAPI3 。 官方文档 openapi3 使用十分方便,做到这里后,你可以直接通过以下网址访问 swagger 页面。 1. @OpenAPIDefinition + @Info 用于定义整个 API 的信息,通常放在主应用类上。可以包括 API 的标题、描述、版本等信

    2024年01月22日
    浏览(57)
  • springBoo3.0集成knife4j4.1.0(swagger3)

    温馨提示: springBoot 版本 3.0+ knife4j 版本 4.1.0  添加依赖:knife4j包含了swagger,openapi3中的依赖,所以加这一个就行。 yml文件中配置: 然后,就可以启动测试输入地址http://ip:port/doc.html  注解的基本使用可以看下这里:swagger3注解和swagger2的区别  这里主要提下请求参数为文件

    2024年02月05日
    浏览(38)
  • Spring Boot3整合knife4j(swagger3)

    目录 1.前置条件 2.导依赖 3.配置 已经初始化好一个spring boot项目且版本为3X,项目可正常启动。 作者版本为3.2.2 初始化教程: 新版idea创建spring boot项目-CSDN博客 https://blog.csdn.net/qq_62262918/article/details/135785412?spm=1001.2014.3001.5501 knife4j官网: Knife4j · 集Swagger2及OpenAPI3为一体的增强

    2024年01月23日
    浏览(45)
  • springboot2.7以上版本配置swagger3.0.0版本浏览器无法打开swagger-ui

    1.最实用解决方式:将pom里的swagger依赖降到2.9.0即可 过低无法启动项目 1.2 Springboot2.6以后将SpringMVC 默认路径匹配策略从AntPathMatcher 更改为PathPatternParser Springfox 使用的路径匹配是基于AntPathMatcher的,而Spring Boot 2.6.X使用的是PathPatternMatcher 2.3.0.0版本swagger2访问地址为:http://loca

    2024年02月11日
    浏览(31)
  • Swagger3学习笔记

    参考https://blog.csdn.net/YXXXYX/article/details/124952856 https://blog.csdn.net/m0_53157173/article/details/119454044 不加会报错 访问http://localhost:8080/swagger-ui/index.html Docket 是一个配置类,用于配置 Swagger 的文档生成规则。通过创建一个 Docket 实例,您可以指定要生成的文档的详细信息,例如 API 的基

    2024年02月13日
    浏览(47)
  • swagger3.0配置化

    2024年02月06日
    浏览(40)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包