当前位置：首页 > news >正文

Swagger使用

news 来源：原创 2025/5/16 11:32:25

在前后端分离和微服务架构盛行的今天，API 的设计、开发和文档管理变得尤为重要。想象一下，后端开发人员完成了一个复杂的 API 接口，如何快速且清晰地向前端同事、测试人员甚至外部合作伙伴展示接口的功能、参数和响应格式？传统的手写文档不仅效率低，而且难以实时更新，容易与实际接口脱节。这时候，Swagger 就成为了开发者的得力助手。

一、Swagger 是什么？

Swagger 是一个用于生成、描述、调用和可视化 RESTful Web 服务的开源工具集，它以简洁的方式将 API 文档与代码进行整合，实现了 API 文档的自动化生成和动态更新。Swagger 包含多个组件，核心部分是 Swagger 规范（现在称为 OpenAPI 规范），它定义了 API 的描述格式；同时，Swagger UI 提供了美观且交互式的 API 文档界面，开发者可以直接在界面上查看接口信息、测试接口；Swagger Codegen 则可以根据 API 规范生成不同语言的客户端和服务器端代码。通过这些组件的协同工作，Swagger 大大降低了 API 的沟通成本和开发成本。

二、为什么使用 Swagger？

自动化文档生成：Swagger 能根据代码中的注解自动生成 API 文档，避免手动编写文档的繁琐与错误，且文档会随着代码的更新而实时变化，始终保持准确性。
可视化与交互性：Swagger UI 提供了直观的可视化界面，不仅可以查看 API 的详细信息，还能直接在页面上对接口进行测试，方便调试和验证接口功能，减少前后端联调的时间成本。
提高协作效率：清晰的 API 文档让团队成员之间的沟通更加顺畅，前端开发人员可以根据文档提前进行开发，测试人员也能快速了解接口的功能和参数，提高整体开发效率。
多语言支持：Swagger Codegen 支持生成多种编程语言的代码，方便不同技术栈的团队快速接入 API，降低开发门槛。

三、在 Spring Boot 项目中集成 Swagger

依赖引入

先引入maven依赖，这里使用我们直接使用Knife4j 框架

knife4j-spring-boot-starter 是 Knife4j 框架的 Spring Boot 集成 starter，它会自动提供默认的 HTML 界面。Knife4j 是基于 Swagger 的增强 UI 组件，用于生成美观的 API 文档。

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>

配置 Swagger

在 Spring Boot 项目中创建一个配置类，用于启用 Swagger 并进行相关配置。

/*** 配置类，注册web层相关组件*/
@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {@Autowiredprivate JwtTokenAdminInterceptor jwtTokenAdminInterceptor;/*** 注册自定义拦截器** @param registry*/protected void addInterceptors(InterceptorRegistry registry) {log.info("开始注册自定义拦截器...");registry.addInterceptor(jwtTokenAdminInterceptor).addPathPatterns("/admin/**").excludePathPatterns("/admin/employee/login");}/*** 通过knife4j生成接口文档* @return*/@Beanpublic Docket docket() {ApiInfo apiInfo = new ApiInfoBuilder()//主题.title("苍穹外卖项目接口文档")//版本号.version("2.0")//简介.description("苍穹外卖项目接口文档").build();Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).select()//扫描的包名.apis(RequestHandlerSelectors.basePackage("com.sky.controller")).paths(PathSelectors.any()).build();return docket;}/*** 设置静态资源映射* @param registry*/protected void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}
}

接着我们访问http://localhost:8080/doc.html即可