欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

SpringMVC配置Swagger2

程序员文章站 2022-07-02 16:10:35
...

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

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)

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

******/

SpringMVC配置Swagger2

6. 结果展示

SpringMVC配置Swagger2

SpringMVC配置Swagger2

7. 项目引入shiro的影响

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

的确,你通过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配置没影响的结论。如果还要其他问题,可以通过756795605这个QQ联系我