SpringBoot 통합 Swagger 예제 분석

1. 인터페이스 문서 개요

swagger는 인기 있는 실시간 인터페이스 문서 생성 도구입니다. 인터페이스 문서는 현재 프론트엔드와 백엔드 분리 프로젝트에 없어서는 안될 도구입니다. 프론트엔드와 프론트엔드 개발에 앞서 백엔드는 먼저 인터페이스를 기반으로 인터페이스 문서를 생성해야 합니다. 문서. 양 당사자의 개발이 완료된 후 공동 디버깅 및 테스트가 수행됩니다.

그래서 인터페이스 문서는 실제로 개발 전 두 당사자 간의 합의입니다. 일반적으로 인터페이스 문서는 오프라인과 실시간으로 구분됩니다. 오프라인 인터페이스 문서 도구에는 단어(Wu와 동일), YAPI, Xiaoyaoji 등이 포함됩니다. 이러한 종류의 문서는 프로그래머가 작성해야 하며 일반적으로 인터페이스 테스트 기능이 있습니다. 일반적으로 개발자는 먼저 오프라인 인터페이스 문서에 정보를 작성한 다음 참조 개발을 위해 프런트엔드 담당자에게 전달합니다. 가장 큰 단점은 인터페이스 프로그램이 변경되면 위의 내용을 다시 유지해야 한다는 것입니다. 이는 매우 번거롭고 정말 번거롭습니다.

실시간 인터페이스 문서는 코드를 기반으로 해당 인터페이스 문서를 자동으로 생성할 수 있습니다. 장점은 코드가 변경되면 생성된 인터페이스 문서가 자동으로 업데이트된다는 것입니다. 제때에 풀려나기만 하면 된다. 하지만 코드를 기반으로 자동 생성되기 때문에 코드의 침해성이 높고 프로젝트 코드에서 인터페이스 문서 생성을 위한 관련 코드를 통합해야 한다는 점이 가장 큰 단점이다. 실시간 인터페이스 문서화를 위한 솔루션은 많지만 Swagger는 여전히 가장 영향력 있는 솔루션 중 하나입니다.

2. SpringBoot는 swagger2를 통합합니다

공식 웹사이트 주소: swagger.io 물론 공식 웹사이트는 모두 영어로 되어 있어 꽤 번거로운 것 같습니다. 제 단계를 따르시기 바랍니다. 매우 간단합니다.

동시에 한 가지 말씀드리고 싶습니다. swagger는 일반적으로 사용되는 두 가지 버전인 swagger2와 swagger3으로 나뉩니다. 둘 사이의 차이는 그다지 크지 않습니다. 주로 종속성과 주석을 최적화합니다. Swagger2는 두 개의 jar 패키지를 도입해야 하고 swagger3은 하나만 필요합니다. 사용에는 큰 차이가 없습니다. 다음은 swagger2를 예로 들어 설명합니다.

2.1 종속성 소개

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

2.2 구성 소개

먼저 주석 @EnableSwagger2를 추가해야 합니다. 이 주석을 SpringBoot 시작 클래스에 추가하거나 구성 클래스를 사용자 정의하여 여기에 넣을 수 있습니다. 이 주석을 추가한 후에는 프로젝트에서 Swagger 기능을 활성화했음을 의미합니다.

두 번째 방법을 사용하여 구성 클래스를 직접 정의하고 Docket 구성을 추가할 수도 있습니다. 소위 Docket 구성은 설정 이름, 연락처 등과 같은 인터페이스 문서 세트(프로젝트 또는 버전)의 구성입니다.

config 폴더 아래에 SwaggerConfig 클래스를 추가합니다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 设置多个：
     *
     * @Bean
     *     public Docket appApi() {
     *
     *         List<Parameter> pars = new ArrayList<>();
     *         ParameterBuilder token = new ParameterBuilder();
     *         token.name("token").description("用户令牌").modelRef(new ModelRef("string")).parameterType("header").required(false)
     *                 .build();
     *         pars.add(token.build());
     *
     *         return new Docket(DocumentationType.SWAGGER_2).select().paths(regex("/app/.*")).build()
     *                 .globalOperationParameters(pars).apiInfo(pdaApiInfo()).useDefaultResponseMessages(false)
     *                 .enable(enableSwagger)
     *                 .groupName("appApi");
     *
     *     }
     *
     *     @Bean
     *     public Docket adminApi() {
     *
     *         List<Parameter> pars = new ArrayList<>();
     *         ParameterBuilder token = new ParameterBuilder();
     *         token.name("token").description("用户令牌").modelRef(new ModelRef("string")).parameterType("header").required(false)
     *                 .build();
     *         pars.add(token.build());
     *         return new Docket(DocumentationType.SWAGGER_2).select().paths(regex("/admin/.*")).build()
     *                 .globalOperationParameters(pars).apiInfo(pdaApiInfo()).useDefaultResponseMessages(false)
     *                 .enable(enableSwagger)
     *                 .groupName("adminApi");
     *
     *     }
     *
     *
     * @return
     */

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.lsqingfeng.action.swagger.controller")).paths(PathSelectors.any())
                .build().globalOperationParameters(setHeaderToken());

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("action-swagger").description("swagger实战").termsOfServiceUrl("")
                .version("1.0").build();
    }

    /**
     * @Description: 设置swagger文档中全局参数
     * @param
     * @Date: 2020/9/11 10:15
     * @return: java.util.List<springfox.documentation.service.Parameter>
     */

    private List<Parameter> setHeaderToken() {
        List<Parameter> pars = new ArrayList<>();
        ParameterBuilder userId = new ParameterBuilder();
        userId.name("token").description("用户TOKEN").modelRef(new ModelRef("string")).parameterType("header")
                .required(true).build();
        pars.add(userId.build());
        return pars;
    }
}

위는 구성 예시이고 setToken 메소드도 설정되어 있는데, 이는 문서를 생성하는 모든 인터페이스에는 헤더 유형의 토큰 매개변수가 포함되어야 함을 의미합니다.

2.3 컨트롤러에 주석 추가

인터페이스 문서에 대한 직접적인 설명은 이 인터페이스의 기능, 매개변수 이름, 반환 값 이름 등과 같이 주로 컨트롤러 수준에 있습니다. 이러한 값의 경우 컨트롤러의 메서드, 요청 매개변수 및 반환 매개변수에 해당 주석을 추가해야 swagger가 해당 인터페이스 문서를 생성하는 데 도움이 될 수 있습니다. 앞서 말씀드렸던 기존 코드에 대한 침입입니다.

사례를 작성해 보겠습니다.

먼저 vo 패키지를 만들고 그 안에 요청과 해당 매개변수를 작성한 다음 JavaBean을 사용하여 요청과 응답의 데이터 구조를 정의합니다. 해당 주석을 여기에 추가해야 합니다.

Request 클래스:

package com.lsqingfeng.springboot.vo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
 * @className: SwaggerReqVO
 * @description:
 * @author: sh.Liu
 * @date: 2022-03-22 19:19
 */
@Data
@ApiModel("创建Swagger请求参数")
public class SwaggerReqVO {

    @ApiModelProperty("id")
    private Integer id;

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("性别")
    private Integer gender;
}

Response 클래스:

package com.lsqingfeng.springboot.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @className: SwaggerResVO
 * @description:
 * @author: sh.Liu
 * @date: 2022-03-22 19:20
 */
@Data
@ApiModel("创建Swagger响应结果")
public class SwaggerResVO {

    @ApiModelProperty("id")
    private Integer id;

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("性别")
    private Integer gender;

    @ApiModelProperty("啥啥")
    private String what;
}

@ApiModel 주석과 @@ApiModelProperty 주석은 여기에서 각각 엔터티 이름과 엔터티 이름을 정의하는 데 사용됩니다. 인터페이스 문서를 생성할 때 표시하기 편리한 필드입니다.

컨트롤러를 다시 살펴보겠습니다.

package com.lsqingfeng.springboot.controller;

import com.lsqingfeng.springboot.vo.SwaggerReqVO;
import com.lsqingfeng.springboot.vo.SwaggerResVO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

/**
 * @className: SwaggerController
 * @description: swagger 接口测试
 * @author: sh.Liu
 * @date: 2022-03-22 19:18
 */
@RestController
@RequestMapping("/swagger")
@Api(value = "用户接口", tags = {"用户接口"})
public class SwaggerController {

    @ApiOperation("新增用户")
    @PostMapping("save")
    public String save(@RequestBody SwaggerReqVO req) {
        return "success";
    }

    @GetMapping("getById")
    @ApiOperation("根据条件查询用户")
    public SwaggerResVO getById(@RequestBody SwaggerResVO req) {
        return new SwaggerResVO();
    }
}

@Api 주석과 @ApiOperation 주석은 각각 인터페이스 그룹 이름과 인터페이스 이름을 표시하는 데 사용됩니다. 이제 프로젝트를 시작합니다.

이 오류가 보고되었습니다.

온라인으로 검색하는 이유는 SpringBoot2.6 버전이 Swagger2.9.2와 호환되지 않기 때문입니다. 어떤 사람들은 구아바 패키지 버전이 너무 낮아서 발생한다고도 합니다.

모두 따로 시도해 보았는데, 구아바의 높은 버전 의존성을 대체하는 문제가 여전히 존재합니다.

이 문제의 주된 이유는 실제로 SpringBoot 버전이 너무 높기 때문입니다. SpringBoot2.5.x 이하 버전을 사용하고 있다면 문제가 없습니다.

Spring Boot 2.6.X는 PathPatternMatcher를 사용하여 경로를 일치시킵니다. Swagger에서 참조하는 Springfox에서 사용하는 경로 일치는 AntPathMatcher를 기반으로 합니다.

그래서 문제를 해결하려면 구성을 추가하고 springBoot MVC의 도로 매칭 모드를 수정하세요.

springBoot 구성 파일에 구성 추가:

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

yml 형식 구성 파일인 경우:

문제를 해결하려면 다시 시작하세요.

액세스 주소: ip:포트 번호/swagger-ui.html

正常情况就可以看到我们的界面了。一会再说非正常情况。由于我们只给用户接口添加了注解，所有用户接口是可以直接观察中文文档的。而剩下的两个接口，由于没添加注解，所以都是以默认的形式展示的。

点开接口，我们可以看到接口中的想详细信息

点击model,可以看到字段的中文描述。点击 Try it out,就可以直接调试接口。同时注意接口中都让填一个token,这就是我们之前的设置成效了。

截止到目前其实swagger的集成就已经完毕了，主要就是根据我们的注解生成文档，并且可以在线调用调试。开发的时候，我们只需要把Controller这一层的请求和响应，以及方法描述等内容先开发完毕，就可以提供给前端让他们参照开发了。

2.4 [404]问题解决

正常情况我们按照上面的步骤就可以出现页面，但是有些时候可能是由于springBoot的版本过高导致的，我们输入之前的地址，出现404的情况，这个主要是由于项目中无法读取到swagger依赖包下的页面导致的。如果出现了这个问题，我们可以添加一个配置类，让他实现WebMvcConfigurer 接口，在添加一个方法：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
    registry.addResourceHandler("swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
}

完整代码如下：

package com.lsqingfeng.springboot.config;

import com.lsqingfeng.springboot.interceptor.TokenInterceptor;
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.WebMvcConfigurer;

/**
 * @className: WebMvcConfig
 * @description:webMvc配置
 * @author: sh.Liu
 * @date: 2022-01-13 09:51
 */
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {


    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

这个时候在启动就可以了！

2.5 替换UI

上面的整个过程已经完成了，但是生成的接口文档的页面，其实很多人不太喜欢，觉得不太符合国人的使用习惯，所有又有一些大神，提供了其他的UI测试页面。这个页面的使用还是比较广泛的。

修改方式：只需引入一个依赖包：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

然后把刚才实现的那个的那个方法再添加一条：

registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");

完成代码：

package com.lsqingfeng.springboot.config;

import com.lsqingfeng.springboot.interceptor.TokenInterceptor;
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.WebMvcConfigurer;

/**
 * @className: WebMvcConfig
 * @description:webMvc配置
 * @author: sh.Liu
 * @date: 2022-01-13 09:51
 */
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

//    @Override
//    public void addInterceptors(InterceptorRegistry registry) {
//        //拦截
//        registry.addInterceptor(new TokenInterceptor())
//                .addPathPatterns("/**")
//                .excludePathPatterns("/login");
//    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }
}

重新启动项目： 访问路径发生了变化：** ip:端口号/doc.html**

页面出现了。我们在看看我们的用户接口：

这个风格确实更加的直观，同时也是可以直接进行调试的。大部分的swagger都用的这个风格的文档。

三. SpringBoot集成swagger3

上面已经很详细的讲解了swagger2的集成方式，而swagger3的集成方式更加的简洁一些。

首先引入依赖：

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

然后是替换注解： swagger2使用的开启注解是： @EnableSwagger2

而在swagger3中，这个注解要换成： @EnableOpenApi

配置类：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30) // v2 不同
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swaggerv3.controller")) // 设置扫描路径
                .build();
    }
}

要注意，里边的版本类型换成了 OAS_30, 就是swagger3的意思。

OAS 是 OpenAPI Specification 的简称，翻译成中文就是 OpenAPI 说明书。

同时访问地址：原始地址，也就是没换UI的地址： localhost:8080/swagger-ui/index.html这个要和swagger2区分开。

swagger3的原始UI风格也发生了一些变化：

同时swagger3也是可以更换UI的。方法和swagger2一样。

四. swaggerUI 拦截器和跨域冲突处理

如果我们的项目中有关于跨域的处理，同时还有拦截器，然后还要使用swagger，这种情况大家要注意了，有可能我们的拦截器会将swagger中的页面路径拦截掉导致swagger页面出不来，当我们在拦截器中把swagger的页面排除掉的时候，也有可能会导致跨域配置的失效。

具体解决方案简单提一下：

拦截器：

/**
 * 拦截器配置
 *
 * @author liuShuai
 */
@Configuration
public class InterceptorConfig implements WebMvcConfigurer {
 
    @Bean
    public TokenInterceptor tokenInterceptor() {
        return new TokenInterceptor();
    }
 
 
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry
                .addInterceptor(tokenInterceptor())
                .addPathPatterns("/**")
                .excludePathPatterns("/user/login")
                .excludePathPatterns("/user/downloadExcel")
                .excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**");
    }
 
    @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/");
    }
}

跨域配置：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
import org.springframework.web.filter.CorsFilter;
 
/**
 * @className: CorsConfig
 * @description:
 * @author: sh.Liu
 * @date: 2020-12-02 10:16
 */
@Configuration
public class CorsConfig {
 
    @Bean
    public CorsFilter corsFilter() {
        CorsConfiguration config = new CorsConfiguration();
        config.addAllowedOrigin("*");
        config.setAllowCredentials(true);
        config.addAllowedMethod("*");
        config.addAllowedHeader("*");
        UrlBasedCorsConfigurationSource configSource = new UrlBasedCorsConfigurationSource();
        configSource.registerCorsConfiguration("/**", config);
        return new CorsFilter(configSource);
    }
}

用这两种方式去配置，就可以让他们和平共处了。

另： 配套项目代码已托管中gitCode: gitcode.net/lsqingfeng/…

分支： feautre/MybatisPlus

위 내용은 SpringBoot 통합 Swagger 예제 분석의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!