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

Swagger-01.介绍和使用方式

news 2025/8/24 21:01:35

一.Swagger介绍

有了接口文档，我们就可以根据接口文档来开发后端的代码了。如果我们开发完了某个功能，后端如何验证我们开发的是否正确呢？我们就需要测试，使用Swagger就可以帮助后端生成接口文档，并且可以进行后端的接口测试。Swagger是后端非常常见的技术。

直接使用Swagger有些繁琐，因此我们使用Knife4j，它是为Java MVC框架集成Swagger生成Api文档的方案。他对Swagger进行了封装，简化了相应的操作。

要使用Knife4j，就要在sky-server工程的pom文件中导入相应的坐标。<version>标签使用了版本锁定，在sky-server工程的父工程sky-take-out的pom文件中使用<dependencyManagement>标签集中进行了版本配置。

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

二.Swagger使用方式

在WebMvcConfiguration这个配置类中加入docket()方法。该方法上面加上一个@Bean注解，代表该方法由spring创建管理该对象，首先创建apiInfo对象构建我们生成的接口文档，title标题，version版本，description描述信息。该对象构造好后，就需要将这个Docket对象创建出来，创建时指定SWAGGER版本为SWAGGER_2，将信息传入，并指定生成接口需要扫描的包，会扫描该包及其子包。扫描到里面的类以及类中的方法，通过反射解析里面的方法，最终生成接口文档。

在配置类中设置静态资源映射，同样编写方法addResourceHandlers()，将/doc.html(固定的)和/webjars映射到该类路径下面。

WebMvaConfiguration.class

package com.sky.config;import com.sky.interceptor.JwtTokenAdminInterceptor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;/*** 配置类，注册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) {    // 方法名固定，因为是重写了WebMvcConfigurationSupport这个父类中的方法。registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}
}