springboot整合swagger

最新推荐文章于 2025-04-22 13:12:43 发布

辛苦cv的小hui

最新推荐文章于 2025-04-22 13:12:43 发布

阅读量1.1k

点赞数 21

文章标签： spring boot 后端 java spring servlet intellij-idea spring cloud

本文链接：https://blog.youkuaiyun.com/qq_65356881/article/details/139826067

版权

什么是swagger

Swagger是一个在软件开发中广泛使用的工具，主要用于生成、描述、调用和可视化RESTful风格的Web服务。以下是对Swagger的详细解释：

定义和概述：
- Swagger是一套基于OpenAPI规范构建的开源工具，旨在简化API的开发、描述、调用和可视化过程。
- 它允许开发人员通过编写和维护一份描述文件（通常为YAML或JSON格式）来自动生成API文档，并确保文档与代码保持同步。
主要功能和特点：
- 代码与文档同步：Swagger能够实时地根据代码的变化更新API文档，确保前后端开发人员使用的API描述始终保持一致。
- 跨语言支持：Swagger支持多种编程语言，使得不同技术栈的团队能够共同使用和维护同一份API文档。
- 交互式文档：Swagger UI可以将编写的OpenAPI规范呈现为交互式的API文档，用户可以直接在文档页面尝试API的调用。
- 版本控制：Swagger工具提供对接口的版本控制功能，允许开发人员展示和对比不同版本的接口文档。
- 模拟请求：开发人员可以使用Swagger UI模拟请求，以便在实际调用API之前验证其功能和性能。
- 自动生成代码：Swagger Codegen可以根据OpenAPI规范定义的API生成服务器存根和客户端SDK，简化构建过程。
主要组成部分：
- Swagger Editor：基于浏览器的编辑器，用于编写OpenAPI规范（YAML或JSON配置）。
- Swagger UI：将OpenAPI规范呈现为交互式的API文档，方便用户查看和测试API。
- Swagger Codegen：通过OpenAPI规范定义的API生成服务器存根和客户端SDK的模板驱动引擎。
使用场景：
- 在前后端分离的开发过程中，Swagger可以帮助前后端开发人员通过一份统一的API文档进行高效的交互和协作。
- 在API版本迭代和升级时，Swagger的版本控制功能可以确保开发人员能够清晰地了解不同版本之间的差异和变化。
- 在API测试和验证阶段，Swagger UI的模拟请求功能可以帮助开发人员在实际调用API之前验证其功能和性能。
集成与配置：
- Swagger可以集成到各种开发框架和工具中，如Spring Boot、Node.js等。
- 通过配置SwaggerConfig类和相关属性，开发人员可以控制Swagger在生产环境和开发环境中的行为。

springboot整合swagger

添加依赖

maven:

<dependency>  
    <groupId>io.springfox</groupId>  
    <artifactId>springfox-boot-starter</artifactId>  
    <version>3.0.0</version> 
</dependency>

gradle:

implementation 'io.springfox:springfox-boot-starter:3.0.0'

配置Swagger

创建一个配置类来配置Swagger。例如，你可以创建一个名为SwaggerConfig的类，并使用@Configuration和@EnableSwagger2（如果你使用的是2.x版本）或@EnableOpenApi（如果你使用的是3.x版本）注解。

对于Swagger 3.x（OpenAPI 3），配置方法如下：

在yml文件添加一个字段用来确认是否开启swagger:

swagger:
  enabled: true

创建一个config注入swagger

import io.swagger.v3.oas.models.OpenAPI;  
import io.swagger.v3.oas.models.info.Info;  
import org.springframework.context.annotation.Bean;  
import org.springframework.context.annotation.Configuration;  
import springfox.documentation.oas.annotations.EnableOpenApi;  
import springfox.documentation.spi.DocumentationType;  
import springfox.documentation.spring.web.plugins.Docket;  
  
@Configuration  
@EnableOpenApi  
public class SwaggerConfig {  

    @Value("${swagger.enabled}")
    Boolean swaggerEnabled;//是否开启swagger
  
    @Bean  
    public Docket api() {  
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                // 是否开启swagger
                .enable(swaggerEnabled)
                .select()
                // 过滤条件，扫描指定路径下的文件
                .apis(RequestHandlerSelectors.basePackage("你的包名"))
                // 指定路径处理，PathSelectors.any()代表不过滤任何路径
                .paths(PathSelectors.any())
                .build();
    }  
  
    private Info apiInfo() {  
        return new Info(  
                "My API Title", // 标题  
                "My API Description", // 描述  
                "1.0", // 版本  
                "Terms of service", // 服务条款  
                new Contact("Contact Name", "www.example.com", "contact@example.com"), // 联系人信息  
                "License of API", // 许可  
                "API license URL", // 许可URL  
                Collections.emptyList() // 扩展信息  
        );  
    }  
}

添加注解来自定义文档上内容

控制器和方法

在你的控制器和方法上添加注解

例如:

@Api是这个控制器在swagger文档中显示的名称

@Apioperation是这个方法在swagger文档中显示的名称

@Api(tags = "用户相关接口")
@RestController
@RequestMapping("/user")
public class UserController {
    @Autowired
    private UserService userService;

    @ApiOperation("登录")
    @PostMapping("/login")
    public R userLogin(@RequestBody User user) {
        //你的业务代码...
    }
}

实体类

只要controller接口中，返回值存在实体类，它就会被扫描到swagger,但是如果你使用了统一返回格式就要在实体类上面添加@ApiModel,参数上使用@ApiModelProperty

例如:

@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("密码")
    private String password;
//  getter和setter方法省略
}

如果你设置了拦截器

可以这样放行关于swagger的请求

package com.certificateManage.config;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.*;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {


    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new MyInterceptor())
                .addPathPatterns("/api/**") // 拦截以/api/开头的请求  
                .excludePathPatterns("/swagger-ui.html", "/v3/api-docs/**", "/webjars/**"); // 排除Swagger UI和相关资源  
    }
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

    }
    
}

注意:

确保你的控制器类和方法上有正确的注解（如@RestController、@GetMapping、@PostMapping等），这样Swagger才能正确地识别和生成API文档。
如果你的API需要身份验证或授权，你还需要在Swagger配置中相应地配置安全性设置。
随着版本的更新，Swagger的配置和用法可能会发生变化。因此，请确保查阅你正在使用的版本的官方文档以获取最准确的信息。

swagger官方文档:https://swagger.io/docs/