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

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使用

1. 新建项目导入依赖

          	  <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>

2. 配置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.csdn.net/qq_38371367")
		.contact("飞客不去")
		.version("1.0")
		.build();    }} 

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

swagger-ui界面中文化

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

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

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

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

3. 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>          

4. 在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）：

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

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

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

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);    }}

4. maven打包方式选择：

   1. 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>
   

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

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

问题总结：

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

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