SpringMVC配置Swagger2

先把配置清单摆上，然后再讲下再配置的时候遇到的坑

1. pom配置

<!-- 
这里有几点需要注意的，就是jackson的版本号与swagger的版本号问题，我尝试过jackson的版本是2.4，然后swagger的版
本是2.7的，配置不成功，后面把swgger的版本号降成2.4才可以。下面的jackson不需要全部配置，只需要配置jackson-
databind即可，如果你的项目中有jackson的v1版本jackson-all-1.7.6.jar，那么你就要注意这个版本与你配置的
jackson2.0版本是否冲突了。我的做法是把jackson1.0版本的引用去掉，然后使用下面jackson的3个jar包。jackson的2.0版本，把jackson的jar包拆成3个了。
 -->
		<!--jackson-->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>2.4.3</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.4.3</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
            <version>2.4.3</version>
        </dependency>

        <!--springfox的核心jar包-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
        </dependency>
        <!--springfox-ui的jar包(里面包含了swagger的界面静态文件)-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>

2. SwagerConfig配置

//@Configuration和@WebAppConfiguration都可以使用，有的博客写果你的项目引入junit测试，此处需要使用@WebAppConfiguration，如果没有使用junit使用@Configuration
//@WebAppConfiguration
//这个ComponentScan我配置的时候没有用处，通过限定要生成文档的controller是通过apis()和paths()控制的
//@ComponentScan(basePackages = "com.fh.controller.api.goods")//扫描control
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {
    @Bean
    public Docket api() {
        System.out.println("----XIN----2018/7/11 下午12:58 Line:22,当前类=SwaggerConfig.api()");
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
				/***
					重要的两个方法:
					apis():指定要生成文档的接口包基本路径
					paths():指定针对哪些请求生成接口文档
					参考官方资料：http://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
				****/
                //.apis(RequestHandlerSelectors.any())
              .apis(RequestHandlerSelectors.basePackage("com.fh.controller.api"))
                .paths(PathSelectors.ant("/api/**"))
                .build()
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXX项目接口文档")
                .description("XXX API接口文档")
                .version("1.0.0")
                .termsOfServiceUrl("")
                .license("")
                .licenseUrl("")
                .build();
    }
}

3. application-mvc配置

<!-- 这里有个坑，我把swaggerConfig文件刚开始写在controller中，结果总是会遇到莫名其妙的错误，在SpringMVC中
国，controller该组件由SpringMVC配置文件扫描，所以SwaggerConfig.java不要写在controller中 -->
<!-- 启用注解 -->
<context:annotation-config/>
<!--将静态资源交由默认的servlet处理-->
<mvc:default-servlet-handler/>
<!--重要！配置swagger资源不被拦截-->
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />
<!--重要！将你的SwaggerConfig配置类注入-->
<bean id="swaggerConfig" class="com.fh.config.swagger2config.SwaggerConfig"/>

4. web.xml配置

<servlet-mapping>
    <servlet-name>SpringMVC</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>

5. controller配置（生成环境配置）

@Controller
@RequestMapping(value = "/api/activity")
@Api(value = "/api/activity", tags = "", description = "")
public class ApiGoodsActivityController extends BaseController {

	/**
	 * 
	 * @Description: 营销活动商品
	 * @date: 2017年7月6日 下午8:00:34 
	 * @author: hzx
	 * @param page
	 * @return
	 * @throws
	 */
	@RequestMapping(value = "/get")
	@ResponseBody
	@ApiOperation(value = "", notes = "", httpMethod = "POST", response = ActivityProduct.class)
	@ApiImplicitParams({
			@ApiImplicitParam(name="currentPage", value="当前页", required=true, dataType="Integer", paramType = "query"),
			@ApiImplicitParam(name="showCount", value="显示条数", required = true, dataType = "Integer", paramType = "query"),
			@ApiImplicitParam(name="activityCode", value="活动编码", required = true, dataType = "String", paramType = "query")
	})
	public Object getDiscountActivityGoods(Page page) {
		String[] paramArray = new String[] { "currentPage", "showCount", "activityCode" };
		String[] valueArray = new String[] { "当前页", "显示条数", "活动编码"};
		Map<String, Object> map = new HashMap<String, Object>();
		PageData pd = new PageData();
		pd = this.getPageData();
		pd.put("status", EmnuGreateProductStatus.VALID_STATUS.getId());
		String code = ExceptionCode.FAIL.getCodeNo();
		ActivityProduct activityProduct = new ActivityProduct();
		ActivityProduct.ActivityRuleDetail activityRuleDetail = activityProduct.instanceActivityRuleDetail();
		return AppUtil.returnObjectNew(activityProduct);
	}
}

/******
	注解相关解释：[swagger注解相关](https://segmentfault.com/a/1190000010465989)

	有几个重要的提一下：
	1.@ApiImplicitParam中的paramType配置成query,这样用HttpServletRequest的getParameter才能拿到
	2.如果返回的实体类要想子啊API文档中展示信息的话，需要在实体类中配置@ApiModel，如下图所示

******/

6. 结果展示

7. 项目引入shiro的影响

如果你的spring项目中引入了shiro，你在遇到问题的时候在网上找的时候，可能有的博客会说要放开shiro对swagger的拦截，如下图所示

的确，你通过shiro的设置，可以直接在域名中访问swagger-ui.html，但是，你接口中还是需要去访问controller的接口，有些接口可能也需求权限，其实，我是不太建议去动shiro，以免引起更多不必要的问题，直接把swagge-ui.html放到项目中，通过controller去访问这个页面即可，这样也避免了接口文档暴露在外面。

8. 总结

在传统的SpringMVC中引入swagge2的确是件很麻烦的事，远不如springBoot引入swagger2方便，我也是花了一天半的时间才把这个给配置好，期间遇到过jar版本冲突问题，shiro影响问题，浏览器打开开发者模式的swagger-ui.html的debugger问题，最后总算整合好了。整合好之后，我把shiro回复原样，发现其实除了无法在没登录的情况下访问swagger-ui.html外,其他没有影响，所以才确定了shiro其实对swagger配置没影响的结论。