SpringMVC配置Swagger2

待我称王封你为后i 2022-05-20 04:59 245阅读 0赞

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

## 1. pom配置 ##

<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>
    
            
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.4.0</version>
            </dependency>
            
            <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配置 ##

<context:annotation-config/>
    
    <mvc:default-servlet-handler/>
    
    <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />
    
    <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，如下图所示
    
    ******/

![这里写图片描述][70]

## 6. 结果展示 ##

![这里写图片描述][70 1]

![这里写图片描述][70 2]

## 7. 项目引入shiro的影响 ##

> 如果你的spring项目中引入了shiro，你在遇到问题的时候在网上找的时候，可能有的博客会说要放开shiro对swagger的拦截，如下图所示  
> ![这里写图片描述][70 3]

> 的确，你通过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配置没影响的结论。

[70]: /images/20220520/2cc7d18970594a6b907f1925c97a0c0a.png
[70 1]: /images/20220520/5311736d787b4a4da166f6bb66c9c676.png
[70 2]: /images/20220520/2a754a3f832c49fda3f26b417b957742.png
[70 3]: /images/20220520/55cc4b52606645da904b7462d152c50e.png