Swagger接口文档

本文档介绍了如何使用Swagger来实现RESTful API接口的文档化和在线测试。首先,通过添加依赖并配置Swagger,然后在Controller类及方法上添加注解,最后重启项目并访问特定URL进行接口测试。 Swagger提供了一个交互式的Web界面,方便开发者查看和测试API接口。

摘要生成于 C知道 ,由 DeepSeek-R1 满血版支持, 前往体验 >

目录

第一步添加依赖

第二步添加配置

①新建一个config包,写配置类

②加入api注解,在controller类上面 

​编辑

③每个方法上加入@ApiOperation注解,生成对应api

第三步在线测试接口

重启项目打开网页进入访问地址

出现此页面表示成功

 展开查看详情

输入要查询的名字测试

 结果


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

第一步添加依赖

     <!--添加swagger的依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>

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

第二步添加配置

①新建一个config包,写配置类

package com.qiu.config;

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 springfox.documentation.swagger2.annotations.EnableSwagger2;

//表示这个类是一个配置类,会把这个类注入到ioc容器中
@Configuration
//开启swagger2的功能
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //这里一定要标注你控制器的位置
                .apis(RequestHandlerSelectors.basePackage("com.qiu.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Thymeleaf测试")
                .description("SpringBoot整合Thymeleaf测试")
                .termsOfServiceUrl("https://angegit.gitee.io/myblog/")
                .contact(new Contact("niechangan","https://angegit.gitee.io/myblog/","1351261434@qq.com"))
                .version("1.0")
                .build();
    }
}

②加入api注解,在controller类上面 

③每个方法上加入@ApiOperation注解,生成对应api

    //value 简单描述,notes 详细描述
    @ApiOperation(value = "删除用户",notes = "根据id删除用户")
    @DeleteMapping("/deleteById")
    public boolean deleteById( Integer id){
        boolean b = userService.removeById(id);
        return b;
    }

第三步在线测试接口

重启项目打开网页进入访问地址

访问地址:http://localhost:8080/swagger-ui.html

注:端口号要写自己的

出现此页面表示成功

 展开查看详情

 

输入要查询的名字测试

 

 结果

 

### Swagger 不显示接口的原因分析 Swagger 不显示接口可能由多种原因引起,以下是常见的几种情况及其解决方案: #### 1. **Spring Boot 和 Swagger 版本不匹配** 如果 Spring Boot 和 Swagger 的版本不兼容,则可能导致接口无法正常加载。例如,在某些情况下,高版本的 Spring Boot 可能会与低版本的 Swagger 发生冲突[^1]。 解决方法: 确认当前使用的 Spring Boot 和 Swagger 版本是否兼容,并根据官方文档调整依赖版本。可以参考以下 Maven 配置作为示例: ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` --- #### 2. **Controller 路径不在扫描范围内** Swagger 默认只会扫描指定包路径下的 Controller 接口。如果新增模块的 Controller 所在路径未被包含在扫描范围中,则这些接口不会显示[^4]。 解决方法: 修改 `Docket` 配置类中的扫描路径,确保覆盖所有需要展示的模块。例如: ```java @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example")) // 修改为实际包路径 .paths(PathSelectors.any()) .build(); } ``` --- #### 3. **缺少必要的注解** Swagger 显示接口的前提条件之一是 Controller 方法上需有相应的注解(如 `@Api`, `@ApiOperation`)。如果没有正确添加这些注解,Swagger 将忽略该接口。 解决方法: 确保每个 Controller 类和方法都加上了合适的注解。例如: ```java @RestController @RequestMapping("/example") @Api(tags = "Example API") // 添加 Api 注解 public class ExampleController { @GetMapping("/test") @ApiOperation(value = "测试接口", notes = "这是一个简单的 GET 请求") // 添加 Operation 注解 public String test() { return "Hello, World!"; } } ``` --- #### 4. **静态资源配置缺失** 部分场景下,Swagger 文档页面可能因为静态资源映射问题而无法正常渲染接口信息。这通常发生在微服务架构中的一些特殊模块[^3]。 解决方法: 创建一个自定义的 `WebMvcConfigurer` 配置类来补充静态资源映射。例如: ```java @Configuration public class WebMvcConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/**").addResourceLocations( "classpath:/META-INF/resources/", "classpath:/resources/", "classpath:/static/"); } } ``` --- #### 5. **排除特定模块的接口** 在一些框架(如 RuoYi 微服务)中,默认可能会通过配置文件或代码逻辑屏蔽掉某些模块的接口文档生成[^5]。 解决方法: 检查是否存在类似的过滤器配置,例如 `SwaggerProvider.java` 中是否有针对模块名称的筛选规则。如果有需求保留某模块的接口文档,则应移除相关限制。 --- #### 6. **其他潜在因素** - 如果项目中有多个 Profile 或环境切换机制,可能存在不同环境下 Swagger 功能启用状态不同的情况。 - 检查日志输出,寻找更详细的错误提示以便定位问题根源。 --- ### 总结 以上列举了几种常见导致 Swagger 不显示接口的原因以及对应的处理方式。建议逐一排查上述可能性并结合实际情况采取措施解决问题。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

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

抵扣说明:

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

余额充值