Swagger-01.介绍和使用方式

news2025/3/12 2:48:27

一.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 {

    @Autowired
    private JwtTokenAdminInterceptor jwtTokenAdminInterceptor;

    /**
     * 注册自定义拦截器
     *
     * @param registry
     */
    protected void addInterceptors(InterceptorRegistry registry) {
        log.info("开始注册自定义拦截器...");
        registry.addInterceptor(jwtTokenAdminInterceptor)
                .addPathPatterns("/admin/**")
                .excludePathPatterns("/admin/employee/login");
    }

    /**
     * 通过knife4j生成接口文档
     * @return
     */
    @Bean
    public 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/");
    }
}