springmvc spring 集成swagger

ssh简称

 本次业务系统采用的传统应用架构(springmvc spring hibernate),为
 方便系统注册和查看对外提供的接口，可通过 Swagger 集成。

• swagger 与 SwaggerUi介绍

Swagger 为提供一种方便查看、管理、测试的接口，而Springfox-Swagger为
针对spring项目框架提供的一个插件，方便集成swagger,集成后可通过地址栏
访问对外提供的swagger json格式接口数据。

SwaggerUI 为Swagger接口提供了一个统一的页面访问方式，可通过访问页面
进行查看。

集成Swagger步骤如下：

• 1、引入Swagger与Swaggerui maven 坐标

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

注意的问题

• Swagger版本 选择

此处我选择的swagger版本为 2.9.2,是因为业务系统采用的spring的版本
为 4.3.13，对于大家在继承的时候，切记需要选择对应的版本，具体选择
swagger的版本，可通过maven仓库，查看swagger依赖的spring版本，选
择适合自己项目的版本。

• Jar包冲突

 大家在引入新的jar包前，需注意该jar包依赖的jar包是否与项目中其它jar包，
 存在冲突，对于一般的jar冲突，选择采用高版本的jar包，排除低版本的jar。

• Guava jar冲突

错误描述为：
org.springframework.context.ApplicationContextException: 
Failed to start bean 'documentationPluginsBootstrapper'; nested
exception is com.google.common.util.concurrent.ExecutionError:
java.lang.NoSuchMethodError: com.google.common.collect.
FluentIterable.concat(Ljava/lang/Iterable;Ljava/lang/Iterable;)
由于项目中已经存在关于 guava 18.0的jar,但Swagger依赖的为
guava版本为20.0，故需排除guava 18.0的jar，采用20.0的jar.

• 主要依赖核心的jar包

byte-buddy-1.8.12.jar
guava-20.0.jar
mapstruct-1.2.0.Final.jar
springfox-core-2.9.2.jar
springfox-schema-2.9.2.jar
springfox-spi-2.9.2.jar
springfox-spring-web-2.9.2.jar
springfox-swagger2-2.9.2.jar
springfox-swagger-common-2.9.2.jar
springfox-swagger-ui-2.9.2.jar
spring-plugin-core-1.2.0.RELEASE.jar
spring-plugin-metadata-1.2.0.RELEASE.jar
swagger-annotations-1.5.20.jar
swagger-models-1.5.20.jar
jackson-annotations-2.8.0.jar
jackson-core-2.8.10.jar
jackson-databind-2.8.10.jar
classmate-1.4.0.jar
commons-logging-1.2.jar
hamcrest-core-1.3.jar
spring-aop-4.3.13.RELEASE.jar
spring-beans-4.3.13.RELEASE.jar
spring-context-4.3.13.RELEASE.jar
spring-core-4.3.13.RELEASE.jar
spring-tx-4.3.13.RELEASE.jar
spring-web-4.3.13.RELEASE.jar
spring-webmvc-4.3.13.RELEASE.jar
spring-expression-4.3.13.RELEASE.jar
spring-jdbc-4.3.13.RELEASE.jar
spring-orm-4.3.13.RELEASE.jar

• 2、添加Swagger的配置类

package com.xxx.configuration.async;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 *  该配置类主要为启动swagger的扫描和配置
 * @date 2020/07/29
 * @author zombie
 */
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfiguration {

	/**
	 *  Swagger 页面显示提示信息配置
	 * @return
	 */
	@Bean
	public Docket docket() {
		return new Docket(DocumentationType.SWAGGER_2)
                //关闭默认响应状态码如：201,400,401
				.useDefaultResponseMessages(false)
				.apiInfo(apiInfo())
                // 是否开启Swagger
				.enable(true)
				.select()
                //指定swagger扫描的包
				.apis(RequestHandlerSelectors.basePackage("com.xxx.thirdparty"))
                // 通过 ant 匹配
				//.paths(PathSelectors.ant("/resource/*"))
				.build()
				;
	}

	private ApiInfo apiInfo() {
		Contact contact = new Contact("XXX接口文档页面访问地址",
				"http://localhost:8080/archmanager/swagger-ui.html","admin@sinosoft.com.cn");
		return new ApiInfoBuilder()
				.title("XXX新架构资产应用版本信息API接口")
				.description("查询新架构资产信息接口")
				.contact(contact)
				.version("V2.1.4.0")
				.build();
	}	
}

• 注解说明

@Configuration 该注解表示声明的为一个配置类，类似于XML中的beans,其中
可以声明多个bean，本次采用的为Java配置，也可转换为对应的XML配置。

@EnableSwagger2 为开启Swagger的配置注解，用于加载关于Swagger的各种
配置类到容器中。

@EnableWebMvc 开启springmvc相关配置信息，在项目中若存在spring则需使
用该注解。

@Bean 用来声明一个bean,docket主要为页面展示的配置信息

• 3、在springmvc的配置文件中，配置 SwaggerConfiguration bean，将该bean注入到SpringMvc 容器管理

	<!--swagger 配置bean声明  -->
	<bean class=
	"com.picc.configuration.async.SwaggerConfiguration"/>

• 4、在shiro 配置文件中，配置静态资源访问权限为不校验，可直接访问

1)
	<bean id="chainDefinitionSectionMetaSource"
		    class="com.picc.interfaces.shiro.source.ChainDefinitionSectionMetaSource">
		<property name="filterChainDefinitions">
			<value>
				<!-- 静态资源区 -->
				/webjars/**=anon
				/static/**=anon
				/**/js/*.js = anon
				/css/** = anon
				/img/** = anon
				/swagger-ui.html = anon
			
			</value>
		</property>
	</bean>

注意: 由于本项目采用的是shiro安全机制，所有访问资源权限都会经过shiro校验机制，
所以我在shiro配置文件中，对该静态资源配置文件进行配置，其中 anon 为不进行安全校验
可直接通过页面访问。

上述配置的路径，可通过maven下载的springfox-swagger-ui的jar,查看具体目录有哪些，
配置这些，主要为了浏览器可以通过访问地址，进行页面访问swagger配置的接口。

2) 上述静态资源配置文件，若不涉及shiro,也可通过springmvc的静态资源配置文件来配置：

<mvc:resources mapping="/swagger-ui.html" location="classpath:/META-INF/resources/*">
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/*">
<mvc:resources mapping="/css/**" location="classpath:/META-INF/resources/*">
...
springmvc这种配置，我在测试的时候不知道是因为shiro的原因，还是其它的，没有生效。

3) 也可以通过web.xml配置过滤文件
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>/swagger-ui.html</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.png</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.js</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.css</url-pattern>
    </servlet-mapping>

上述三种方式，可根据自己项目进行选择配置

• 4、配置Swagger接口

在 SwaggerConfiguration 配置类中配置的扫描包下，对需要提供的接口，采用
Swagger的注解进行配置，既可。

@Controller
@RequestMapping(value = "/resource")
@Api(value = "ResourceAction",description = "新架构资产相关接口描述",tags = "resources",basePath = "/resource",produces = "application/json")
public class ResourceAction {


	@Autowired
	private ResourceAggregateService resourceAggregateService;
	private static final Logger logger = LoggerFactory.getLogger(ResourceAction.class);
	
	@GetMapping(value = "/applicationVersionRelationInfo")
	@ResponseBody
	@LogAnnotation(description = "获取新架构(微服务、前台应用、组件)的版本依赖关系(元服务使用关系、变更订阅关系))")
	@ApiOperation(value = "获取应用版本使用关系",notes = "获取新架构(微服务、前台应用、组件)的版本依赖关系(元服务使用关系、变更订阅关系))",httpMethod = "Get")
	public ApiResponse<String> applicationVersionRelationInfo(HttpServletRequest request){

		String microServiceArch = request.getParameter("microServiceArch");
		String applicationCode = request.getParameter("applicationCode");
		String versionNo = request.getParameter("versionNo");
		List<ApplicationInfoVo> applicationRelationInfoList = resourceAggregateService.getApplicationRelationInfoList(microServiceArch, applicationCode, versionNo);
		return ApiResponse.ok(JSON.toJSONString(applicationRelationInfoList));
	}
}

注解说明：
    @Api ：声明在类上的注解，主要用于分类，提供一个统一的访问入口
 	@ApiOperation ： 为声明在具体对外提供接口的注解，描述该接口的请求方式，接口描述等

更多注解请参开Swagger的API   

• 5、启动服务，访问地址 http://localhost:8080/archmanager/swagger-ui.html#/ 或http://localhost:8080/archmanager/v2/api-docs

• 访问地址说明

/swagger-ui.html 该地址为页面可查看对外提供的接口图形化展示
/v2/api-docs 该地址为对外提供的接口生成的json数据

第一个地址不可访问，第二个地址可以访问则问题可能为：页面静态资源访问配置
有问题。