SpringBoot集成swagger

一. 接口文档概述

swagger是当下比较流行的实时接口文文档生成工具。接口文档是当前前后端分离项目中必不可少的工具,在前后端开发之前,后端要先出接口文档,前端根据接口文档来进行项目的开发,双方开发结束后在进行联调测试。

所以接口文档其实就是开发之前双方之间的一种约定。通常接口文档分为离线的和实时的。离线的接口文档工具有: word(相当于没说), YAPI, 小幺鸡等,这种文档需要程序员在上面编写,也一般具备接口测试功能。通常是由开发人员先在离线接口文档上编写信息,然后交给前端人员参照开发。最大的弊端是当我们的接口程序发生变动时,需要回过头来维护上面的内容,很麻烦,是真的麻烦。

实时接口文档就是可以根据我们的代码来自动生成相应的接口文档,优点就是我们的代码发生变化时,生成的接口文档也会自动更新,无需我们关注修改,主需要按时发布即可。但是由于是根据代码自动生成的,所以最大的弊端就是代码侵入性强,需要我们在项目代码中集成生成接口文档的相关代码。实时接口文档现在的方案有很多,但是swagger还是其中比较有影响力的一个。

二. SpringBoot集成swagger2

官网地址: swagger.io 当然,官网都是英文的,看起来还是比较麻烦的。建议大家直接按照我的步骤来,还是很简单的。

同时在说一点: swagger分为swagger2 和swagger3两个常用版本。二者区别不是很大,主要对于依赖和注解进行了优化。swagger2需要引入2个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 userApi() {
		return new Docket(DocumentationType.SWAGGER_2).groupName("学习Demo").apiInfo(apiInfo()).select()
				.apis(RequestHandlerSelectors.basePackage("com.dhx.sw2.controller")).paths(PathSelectors.any())
				.build().globalOperationParameters(setHeaderToken());
	}
	// 预览地址:swagger-ui.html
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("Spring 中使用Swagger2构建文档").termsOfServiceUrl("")
				.contact(new Contact("学习Demo ", "", "")).version("1.1").build();
	}

	/**
	 * @Description: 设置swagger文档中全局参数
	 * @param
	 * @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方法,代表生成文档的所有接口中,都要包含一个header类型的token参数。

2.3 给Controller 添加注解

我们接口文档的直接描述主要就是在Controller这一层,比如这个接口的功能,参数的名称,返回值的名称等。这些值我们都需要在Controller上通过给方法上,请求参数和返回参数上添加对应的注解,swagger才能帮我们生成相应的接口文档。这也就是我前面提到的对现有代码的侵入性。

我们来写一个案例。

首先先创建一个po的包,里边写我们的请求和相应参数,使用JavaBean定义出请求和响应的数据结构。注意这里要添加相应的注解:

请求类:

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

@Data
@ApiModel("创建Swagger请求参数")
public class SwaggerReqVO {
    
    @ApiModelProperty("id")
    private Integer id;

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

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

响应类:

package com.dhx.sw2.po;

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

/**
 * 通用响应对象
 */
@ApiModel("创建Swagger响应结果")
public class BaseResult<T> {
    private static final int SUCCESS_CODE = 0;
    private static final String SUCCESS_MESSAGE = "成功";

    @ApiModelProperty("code")
    private int code;

    @ApiModelProperty("消息")
    private String msg;

    @ApiModelProperty("响应数据")
    private T data;

    private BaseResult(int code, String msg, T data) {
        this.code = code;
        this.msg = msg;
        this.data = data;
    }

    private BaseResult() {
        this(SUCCESS_CODE, SUCCESS_MESSAGE);
    }

    private BaseResult(int code, String msg) {
        this(code, msg, null);
    }

    private BaseResult(T data) {
        this(SUCCESS_CODE, SUCCESS_MESSAGE, data);
    }

    public static <T> BaseResult<T> success() {
        return new BaseResult<>();
    }

    public static <T> BaseResult<T> successWithData(T data) {
        return new BaseResult<>(data);
    }

    public static <T> BaseResult<T> failWithCodeAndMsg(int code, String msg) {
        return new BaseResult<>(code, msg, null);
    }

    public static <T> BaseResult<T> buildWithParam(ResponseParam param) {
        return new BaseResult<>(param.getCode(), param.getMsg(), null);
    }

    public int getCode() {
        return code;
    }

    public void setCode(int code) {
        this.code = code;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }


    public static class ResponseParam {
        private int code;
        private String msg;

        private ResponseParam(int code, String msg) {
            this.code = code;
            this.msg = msg;
        }

        public static ResponseParam buildParam(int code, String msg) {
            return new ResponseParam(code, msg);
        }

        public int getCode() {
            return code;
        }

        public void setCode(int code) {
            this.code = code;
        }

        public String getMsg() {
            return msg;
        }

        public void setMsg(String msg) {
            this.msg = msg;
        }
    }
}

这里分别使用了 @ApiModel注解和 @ApiModelProperty 注解定义了实体的名称和字段的名称,方便生成接口文档时展示。

再来看Controller:

/**
 * swagger 接口测试
 */

@Api(value = "用户接口", tags = {"用户接口"})
@RequestMapping("/swagger")
@RestController
public class SwaggerController {

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

    @ApiOperation("根据条件查询用户")
    @GetMapping("getById")
    public BaseResult<SwaggerReqVO> getById() {
        return BaseResult.success();
    }
}

这里使用了@Api注解和 @ApiOperation注解分别标注了接口组名和接口的名称。现在我们启动项目。
在这里插入图片描述
发现报了这个错误。

上网查询原因说是SpringBoot2.6版本和Swagger2.9.2不兼容导致的。 也有人说是由于guava这个包的版本过低导致的。

我都分别试了一下,替换了guava的高版本依赖问题还是存在。

这个问题的主要原因确实是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/");
}

完整代码如下:

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配置
 */
@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/");

完成代码:

 @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.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.dhx.sw2.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的页面排除掉的时候,也有可能会导致跨域配置的失效。

详细的解决方案可以看这一篇博客

具体解决方案简单提一下:
拦截器:

/**
 * 拦截器配置
 */
@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;
 
@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);
    }
}

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

  • 2
    点赞
  • 6
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
要在Spring Boot集成Swagger,你需要做以下几个步骤: 1. 首先,确保你使用的是Spring Boot 2.5.x及之前的版本。因为从Spring Boot 2.6.x开始,Swagger已经从Spring Boot中移除了。 2. 在你的Spring Boot应用中添加Swagger的依赖。在pom.xml文件中,添加以下依赖: ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` 3. 在启动类上添加`@EnableSwagger2`注解。这个注解会启用Swagger的功能。你可以将这个注解直接添加到你的Spring Boot启动类上,或者创建一个单独的配置类,在配置类中添加这个注解。 4. 配置Swagger的相关属性。你可以在`application.properties`或`application.yml`文件中添加以下配置: ```yaml springfox.documentation.swagger.v2.path=/swagger springfox.documentation.swagger.ui.enabled=true ``` 这些配置将指定Swagger的路径和UI的启用状态。 5. 编写API文档。在你的控制器类中,使用Swagger的注解来描述你的API接口。例如,你可以使用`@Api`注解来给你的控制器类添加一个API的描述,<span class="em">1</span><span class="em">2</span><span class="em">3</span> #### 引用[.reference_title] - *1* *2* *3* [SpringBoot教程(十六) | SpringBoot集成swagger(全网最全)](https://blog.csdn.net/lsqingfeng/article/details/123678701)[target="_blank" data-report-click={"spm":"1018.2226.3001.9630","extra":{"utm_source":"vip_chatgpt_common_search_pc_result","utm_medium":"distribute.pc_search_result.none-task-cask-2~all~insert_cask~default-1-null.142^v92^chatsearchT3_1"}}] [.reference_item style="max-width: 100%"] [ .reference_list ]

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

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

抵扣说明:

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

余额充值