swagger-ui和springboot项目结合+springboot静态资源映射

最新推荐文章于 2025-06-12 23:47:33 发布

原创最新推荐文章于 2025-06-12 23:47:33 发布 · 3.5k 阅读

3 ·

CC 4.0 BY-SA版权

SpringBoot 专栏收录该内容

14 篇文章

订阅专栏

本文详细介绍如何在SpringBoot项目中使用Swagger生成RESTful API文档，包括依赖导入、配置类编写、界面汉化及常见问题解决。同时，介绍了Swagger注解的使用方法，帮助开发者快速上手。

swagger-ui：

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
官网：https://swagger.io/springfox
大致原理： springfox的大致原理就是，在项目启动的过种中，spring上下文在初始化的过程，框架自动跟据配置加载一些swagger相关的bean到当前的上下文中，并自动扫描系统中可能需要生成api文档那些类，并生成相应的信息缓存起来。如果项目MVC控制层用的是springMvc那么会自动扫描所有Controller类，并生成对应的文档描述数据.该数据是json格式，通过路径：项目地址/ v2/api-docs可以访问到该数据，然后swaggerUI根据这份数据生成相应的文档描述界面。因为我们能拿到这份数据，所以我们也可以生成自己的页面.springboot和swagger使用

新建项目导入依赖

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

配置swagger配置类


@Configuration
@EnableSwagger2
public class SwaggerConfig{    @Bean    public Docket createRestApi() {        
	return new Docket(DocumentationType.SWAGGER_2)                
		.apiInfo(apiInfo())                
		.select()
		.apis(RequestHandlerSelectors.basePackage("com.aaa.dogs.cats"))
		.paths(PathSelectors.any())                
		.build();    
}    

private ApiInfo apiInfo() {        
	return new ApiInfoBuilder()
		.title("Spring Boot中使用Swagger2构建RESTful API")
		.description("rest api 文档构建利器")
		.termsOfServiceUrl("https://blog.youkuaiyun.com/qq_38371367")
		.contact("飞客不去")
		.version("1.0")
		.build();    }}

配置好之后，项目启动会自动扫描指定的包，如果使用springMVC，则会扫描配置包下的所有的controller层的方法，将所有的接口暴露出来生成文档，只需要访问：项目地址/swagger-ui.html，就可以看到swagger-ui界面，看到所有的接口信息。

swagger-ui界面中文化

参考博客：（https://blog.youkuaiyun.com/itguangit/article/details/78978296）
Spring Boot 默认“约定”从资源目录的这些子目录读取静态资源（优先级从上到下）

	1. src/main/resources/META-INF/resources
	2. src/main/resources/static （推荐）
	3. src/main/resources/public

之前引入的 springfox-swagger-ui 这个包

在浏览器看到的swagger-ui就是此页面。
2. 我们想要中文版的，根据官方提供的方法只需要按照此目录结构，在项目下构建相同目录结构，就可以实现覆盖，我们也不能直接在这里修改源码啊,还记得我们前面提到的 Spring boot 资源目录的优先级吗? 没错,我们只需要在记得项目下创建 META-INF 这个资源目录就行啊
在这里插入图片描述

Spring boot 默认会把我们项目的 src/main/resources/META-INF/resources 覆盖其它的依赖下的文件. 在自己项目中的swagger-ui.html文件中添加两句话在head标签的内部最下面就行

<script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script> 
<script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>

在zh-cn.js里面可以看到，页面英文对应的中文，还支持自己修改自定义

Swagger常用注解

@Api: 描述类/接口的主要用途
@ApiOperation: 描述方法用途
@ApiImplicitParam: 描述方法的参数
@ApiImplicitParams: 描述方法的参数(Multi-Params)

可以在上面创建用户的方法上添加 @ApiImplicitParam(name = “user”, value = “用户详细实体user”, required = true, dataType = “User”)试试看.
@ApiParam:请求属性
@ApiIgnore: 忽略某类/方法/参数的文档

注意与 @ApiModelProperty(hidden = true)不同, @ApiIgnore 不能用在模型数据上
@ApiResponse：响应配置

如: @ApiResponse(code = 400, message = “无效的用户信息”) ,注意这只是在生成的Swagger文档上有效,不要和实际的客户端调用搞混了. 通常我们都是统一JSON返回,用不到这个注解
@ApiResponses：响应集配置
@ResponseHeader: 响应头设置

例如: @ResponseHeader(name=”head1”,description=”response head conf”)
@ApiModelProperty:添加和操作模型属性的数据

SpringBoot静态文件问题

参考博客：（https://www.cnblogs.com/xbq8080/p/7774856.html）：

Spring Boot 默认“约定”从资源目录的这些子目录读取静态资源（优先级从上到下）

	1. src/main/resources/META-INF/resources
	2. src/main/resources/static （推荐）
	3. src/main/resources/public

配置文件配置静态资源以及映射（自定义）

spring 
	mvc: 
		static-path-pattern: /image/**     
	resources:       
		static-locations: file:H:/aaa/image/

以上配置表示在url中访问：/image/** ；映射器会去找磁盘下的H:/xlauncher/image/中的资源，也可以配置成classpath:aaa/image/
3. 在配置文件中这样配置是不推荐的，因为项目这样配置，会造成修改springboot的默认静态资源映射以及打包资源丢失，所以还有一种更优方式来处理这种映射，并且不会覆盖springboot:

 继承 WebMvcConfigurerAdapter 并重写方法 addResourceHandlers
 /*** 自定义静态文件 映射*/
 @Configuration
 public class MyWebAppConfigurer extends WebMvcConfigurerAdapter {    

	@Override    
	public void addResourceHandlers(ResourceHandlerRegistry registry) {                
	//支持：file:/var/lib/tomcat/webapps/xlauncher/image/        
	//支持：classpath:/img1/     
	registry.addResourceHandler("/image/**")
	.addResourceLocations("file:/var/lib/aaa/image/"); 
	super.addResourceHandlers(registry);    }}

maven打包方式选择：

maven打包方式可以自定义

	<build>
		<resources>
			<resource>
				<directory>src/main/java</directory>
				<includes>
					<include>**/*.xml</include>
				</includes>
				<filtering>false</filtering>
			</resource>
			<resource>
				<directory>src/main/resources</directory>
				<includes>
					<include>**/*.yml</include>
				</includes>
				<filtering>false</filtering>
			</resource>
			<resource>
				<directory>src/main/resources</directory>
				<includes>
					<include>**/*.xml</include>
				</includes>
				<filtering>false</filtering>
			</resource>
		</resources>
	</build>

也可以直接使用插件，让springboot去管理资源文件

		<plugin>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-maven-plugin</artifactId>
		</plugin>

问题总结：

导入依赖，编写配置类后，访问:项目地址/+swagger-ui.html 报错404
原因：
1. 在配置文件自定义了静态资源位置
2. swagger配置类下没有swagger资源，即没有controller接口，或者不是springMVC
解决：
1. 使用配置类来做静态资源映射，不修改覆盖springBoot的静态资源映射
2. 检查配置类中指定的扫包
汉化失败：
1. 打包方式问题，应该只选择默认打包插件方式
2. 文件夹目录没有对应

感谢参考博客：
https://blog.youkuaiyun.com/itguangit/article/details/78978296
https://www.cnblogs.com/xbq8080/p/7774856.html