SpringBoot集成Swagger3

于 2025-03-18 20:00:00 发布
阅读量1k 收藏 26
点赞数 29
分类专栏： Spring 文章标签： spring boot 后端 java
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.youkuaiyun.com/jc_hook/article/details/146341631
版权

目录

一、说明

本文主要列举SpringBoot是如何集成Swagger3获得项目的交互式文档。

示例版本
SpringBoot：2.4.3

二、依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>3.0.3</version>
</dependency>

三、配置

配置文件

## 控制是否开启集成文档
swagger.enabled=true


import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;


@Configuration
@EnableOpenApi
//@EnableSwaggerBootstrapUI
public class SwaggerConfig {
    @Value("${swagger.enabled}")
    private boolean enable;

    /**
     * 创建API
     * http:IP:端口号/swagger-ui/index.html 原生地址
     * http:IP:端口号/doc.html bootStrap-UI地址
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30).pathMapping("/")
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                /*.enable(enable)*/
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描指定包中的swagger注解
                .apis(RequestHandlerSelectors.basePackage("路径"))
                // 扫描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.regex("(?!/ApiError.*).*"))
                .paths(PathSelectors.any())
                .build()
                // 支持的通讯协议集合
                .protocols(newHashSet("https", "http"))
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());

    }

    /**
     * 支持的通讯协议集合
     * @param type1
     * @param type2
     * @return
     */
    private Set<String> newHashSet(String type1, String type2){
        Set<String> set = new HashSet<>();
        set.add(type1);
        set.add(type2);
        return set;
    }

    /**
     * 认证的安全上下文
     */
    private List<SecurityScheme> securitySchemes() {
        List<SecurityScheme> securitySchemes = new ArrayList<>();
        securitySchemes.add((SecurityScheme) new ApiKey("token", "token", "header"));
        return securitySchemes;
    }

    /**
     * 授权信息全局应用
     */
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.any()).build());
        return securityContexts;
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo() {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题")
                // 描述
                .description("描述")
                // 作者信息
                .contact(new Contact("jchook", null, null))
                // 版本
                .version("版本号:V.1.0.0")
                //协议
                .license("The Apache License")
                //协议url
                .licenseUrl("http://www.baidu.com")
                .build();
    }
}

四、注解

1.@Api

@Api 注解用于标注一个Controller（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。

属性描述
valueurl的路径值
tags如果设置这个值、value的值会被覆盖
description对api资源的描述
basePath基本路径可以不配置
position如果配置多个Api 想改变显示的顺序位置
producesFor example, “application/json, application/xml”
consumesFor example, “application/json, application/xml”
protocolsPossible values: http, https, ws, wss.
authorizations高级特性认证时配置
hidden配置为true 将在文档中隐藏

示例代码:

@Controller
@Slf4j
@RequestMapping("/person")
@Api(tags = "人员", description = "提供人员信息相关的 Rest API")
public class personController extends BaseController {
	
}

2.@ApiOperation

@ApiOperation 注解在用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。

主要属性:

属性描述
valueurl的路径值
tags如果设置这个值、value的值会被覆盖
description对api资源的描述
basePath基本路径可以不配置
position如果配置多个Api 想改变显示的顺序位置
producesFor example, “application/json, application/xml”
consumesFor example, “application/json, application/xml”
protocolsPossible values: http, https, ws, wss.
authorizations高级特性认证时配置
hidden配置为true 将在文档中隐藏
response返回的对象
responseContainer这些对象是有效的 “List”, “Set” or “Map”.，其他无效
httpMethod“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
codehttp的状态码 默认 200
extensions扩展属性

3.@ApiParam

@ApiParam作用于请求方法上，定义api参数的注解。

主要属性:

属性 描述
name属性名称
value属性值
defaultValue默认属性值
allowableValues可以不配置
required是否属性必填
access不过多描述
allowMultiple默认为false
hidden隐藏该属性
example举例子

代码示例:

public List getPersonList(@ApiParam(value="房间id")String roomId)

4.@ApiImplicitParams、@ApiImplicitParam

@ApiImplicitParams、@ApiImplicitParam 都可以定义参数.

(1).@ApiImplicitParams：用在请求的方法上，包含一组参数说明

(2).@ApiImplicitParam：对单个参数的说明

主要属性：

属性描述
name参数名
value参数的说明、描述
required参数是否必须必填
paramType参数放在哪个地方
dataType参数类型，默认String，其它值dataType=“Integer”
defaultValue参数的默认值

5.@ApiResponses、@ApiResponse

@ApiResponses、@ApiResponse进行方法返回对象的说明。

主要属性：

属性描述
code数字，例如400
message信息，例如"请求参数没填好"
response抛出异常的类

代码示例:

@ApiResponses({
		@ApiResponse(code = 200, message = "请求成功"),
		@ApiResponse(code = 400, message = "请求参数没填好"),
		@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
	}) 
	@ResponseBody
	@RequestMapping("/user")
	public ApiResult getPerson(@RequestParam String personId) {
		...
	}

6.@ApiModel、@ApiModelProperty

@ApiModel用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）。

@ApiModelProperty用来描述一个Model的属性

使用场景

@ApiModel 用在模型类上,对模型类作注解

@ApiModelProperty 用在属性上,对属性作注解

代码演示:

/**
 * <pre>
 *     人员信息类
 * </pre>
 *
 */
@Data
@ApiModel(description= "返回人员信息")
public class PersonQueryVo extends BaseEntity{
 
    @ApiModelProperty(value = "主键", required = true)
    @TableId(value = "id", type = IdType.ID_WORKER)
    private Long id;
    
    @ApiModelProperty(value = "手机号", required = true)
    private String phonenum;
 
    @ApiModelProperty(value = "密码", required = true)
    private String password;
    
    @ApiModelProperty(value = "年龄", required = true)
    private Integer age;
}

7.@PathVariable

@PathVariable用于获取get请求url路径上的参数，即参数绑定的作用，通俗的说是url中"?"前面绑定的参数。

五、访问

启动服务，访问：
ip:port/doc.html
即可看到文档

SpringBoot中集成swagger3（OpenAPI）
记录学习的一些知识，也希望这些记录总结能帮到需要的人！
06-13 1534
SpringBoot中集成swagger3（OpenAPI）
SpringBoot整合Swagger3环境搭建
m0_64245578的博客
10-21 1430
【代码】SpringBoot整合Swagger3环境搭建。
Springboot集成Swagger3详细操作步骤
zhanhjxxx的博客
02-17 1万+
目录 1、添加依赖 2、添加配置文件resources\config\swagger.properties 3、编写Swagger3Config配置类 4、编写Ctronller类 5、启动访问地址： 6、Swagger3常用注解说明 1、添加依赖 <!-- 引入swagger3包 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springf
springboot整合swagger3
吉屋安的博客
06-07 3103
注解表示该方法返回一个 Spring Bean，用于配置 Swagger 的 Docket 对象。类定义了 Swagger 的基本配置和 API 文档信息，使得你可以生成并展示美观的接口文档界面。是 Swagger 的主要配置类，它提供了一系列的配置选项。对象，用于配置接口的认证方式。在这里，我们使用 API Key 的方式进行认证，并通过。对象，用于设置 API 文档的基本信息，包括标题、描述、版本和联系人等。这是一个配置类的声明，使用了。注解，表示这是一个配置类。用于定义认证头的名称，
@ApiImplicitParam注解
aqx63777的博客
07-04 5364
@Api：用在请求的类上，表示对类的说明 tags="说明该类的作用，可以在UI界面上看到的注解" value="该参数没什么意义，在UI界面上也看到，所以不需要配置" @ApiOperation：用在请求的方法上，说明方法的用途、作用 value="说明方法的用途、作用" ...
Springboot之整合Swagger3
热门推荐
百锦再的博客
12-02 1万+
swagger在开发阶段，对开发人员和前端人员非常友好。
Spring Boot整合swagger3
桃花朵朵~
10-22 8651
第一步创建一个spring boot 项目 第二步 pom.xml里引入包 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> 第三步 创建SwaggerConfig
springboot集成swagger3
weixin_44021888的博客
06-11 213
springboot集成swagger3
SpringBoot集成Swagger3（powernode document）源代码
02-14
SpringBoot集成Swagger3（powernode document）源代码 SpringBoot集成Swagger3（powernode document） 一、问题描述 二、使用步骤 2.1 创建SpringBoot项目加入依赖 2.2 application.yml配置文件 2.3 创建...
SpringBoot整合Swagger3生成接口文档过程解析
08-18
主要介绍了SpringBoot整合Swagger3生成接口文档过程解析,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
SpringBoot集成swagger3（powernode CD2207）（教学视频+源代码）
02-10
SpringBoot集成swagger3（powernode CD2207） 零、前期准备 数据库ssm_power_edu.sql 0.1 pom.xml 0.2 application.yml 0.3 实体类 0.4 UserMapper接口 0.5 UserMapper.xml配置文件 0.6 service层接口 0.7 service层...
SpringBoot整合Swagger3
鸟人的博客
06-22 1241
Swagger3可以给我们一个优美人性化的界面来访问和测试后端的接口，下面来看看SpringBoot中怎么整合Swagger3。
Springboot 集成swagger3
baidu_40926496的博客
07-26 1245
2.swagger 启动配置 3.swagger注解 1）启动类中添加 @EnableOpenApi 注解2）controller 添加 @Api(tags=“接口分类名称”)注解3）接口上添加 @ApiOperation(“接口名称”) 注解3）请求响应参数添加 @Schema(name = “字段名”, description = “字段描述”)启动后的ui界面
Springboot集成Swagger3
最新发布
03-13
### Spring Boot 整合 Swagger3 实现 API 文档自动化生成与测试 #### 项目准备 为了使Spring Boot应用程序支持Swagger3并实现API文档的自动生成以及提供在线测试功能，需先确保项目的构建工具配置文件`pom.xml`中包含了必要的依赖项。具体来说，应当加入用于集成Swagger UI和支持OpenAPI 3.0规范描述格式的相关库[^4]。 ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` #### 主应用类设置 接着，在主启动类上添加特定注解来启用增强版的Swagger界面组件——Knife4j，这将为用户提供更加友好美观的操作体验。例如： ```java package com.example.demo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc; @SpringBootApplication @EnableSwagger2WebMvc // 启用Swagger Web MVC支持 public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } } ``` 需要注意的是，对于最新版本的SpringFox（即3.x系列），推荐使用`@EnableSwagger2WebMvc`而非旧式的`@EnableSwagger2`以获得更好的兼容性和性能表现[^3]。 #### 配置Swagger属性 创建一个新的Java配置类用来定义Swagger的具体行为参数，比如基本信息、联系人详情等。下面是一个简单的例子说明如何完成这项工作： ```java @Configuration public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.OAS_30) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo(){ return new ApiInfoBuilder().title("API Title") .description("Description of APIs") .contact(new Contact("Name", "URL", "Email")) .license("License") .licenseUrl("http://url-to-license.com") .version("1.0.0") .build(); } } ``` 这段代码片段展示了怎样通过Docket对象定制化Swagger的行为模式，并指定了扫描控制器所在的包路径以便于自动收集API元数据信息。 #### 访问Swagger UI 一旦上述步骤全部完成后，重启Spring Boot服务端口，默认情况下可以通过浏览器访问`http://localhost:<port>/doc.html`地址查看由Knife4j提供的改进型Swagger UI页面，这里可以浏览到所有已注册的服务接口及其详细说明，同时也允许直接在此界面上发起请求来进行交互式测试操作[^1]。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

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

余额充值