zoukankan      html  css  js  c++  java
  • springmvc集成swagger实现接口文档自动化生成

    一直苦于文档整理工作,因为这是一个很无聊的工作,偶然在网上看到了swagger这东西,感觉不错,于是动手集成了一下,眼前一亮

              Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

            费话少说,下面来看一下集成的过程,我用的环境是:jdk1.8+tomcat7.0+springmvc4.2+maven3.0

    1.首先,通过maven将相关的jar引入项目

        <!-- swagger -->  
                <dependency>  
                    <groupId>com.mangofactory</groupId>  
                    <artifactId>swagger-springmvc</artifactId>  
                    <version>1.0.2</version>  
                </dependency>  
                <dependency>  
                    <groupId>com.fasterxml.jackson.dataformat</groupId>  
                    <artifactId>jackson-dataformat-xml</artifactId>  
                    <version>2.7.4</version>  
                </dependency>  
                <dependency>  
                    <groupId>com.fasterxml.jackson.core</groupId>  
                    <artifactId>jackson-databind</artifactId>  
                    <version>2.7.4</version>  
                </dependency>  
                <dependency>  
                    <groupId>com.fasterxml.jackson.core</groupId>  
                    <artifactId>jackson-annotations</artifactId>  
                    <version>2.7.4</version>  
                </dependency>  
                <dependency>  
                    <groupId>com.fasterxml.jackson.core</groupId>  
                    <artifactId>jackson-core</artifactId>  
                    <version>2.7.4</version>  
                </dependency>  
                <!-- swagger -->  

    2.写一个自定义的swagger的config类

        import org.springframework.beans.factory.annotation.Autowired;  
        import org.springframework.context.annotation.Bean;  
        import org.springframework.context.annotation.ComponentScan;  
        import org.springframework.context.annotation.Configuration;  
        import org.springframework.web.servlet.config.annotation.EnableWebMvc;  
          
        import com.mangofactory.swagger.configuration.SpringSwaggerConfig;  
        import com.mangofactory.swagger.models.dto.ApiInfo;  
        import com.mangofactory.swagger.plugin.EnableSwagger;  
        import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;  
          
        /** 
         * <B>文件名称:</B>SwaggerConfig.java<BR> 
         * <B>文件描述:</B><BR> 
         *  
         * <B>版权声明:</B>(C)2014-2015<BR> 
         * <B>公司部门:</B><BR> 
         * <B>创建时间:</B>2016年6月30日<BR> 
         *  
         * @author  
         * @version  
         */  
        @Configuration  
        @EnableWebMvc  
        @EnableSwagger  
        @ComponentScan("cn.brandwisdom.roomVouchers")  
        public class SwaggerConfig {  
          
            private SpringSwaggerConfig springSwaggerConfig;  
          
              
          
              
            @Autowired  
            public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {  
                this.springSwaggerConfig = springSwaggerConfig;  
            }  
          
            /** 
             * 链式编程 来定制API样式 
             * 后续会加上分组信息 
             * 
             * @return 
             */  
            @Bean  
            public SwaggerSpringMvcPlugin customImplementation() {  
                return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)  
                        .apiInfo(apiInfo())  
                        .includePatterns(".*")  
                        .apiVersion("0.0.1");  
                //.swaggerGroup(PROJECT_NAME);  
            }  
          
            private ApiInfo apiInfo() {  
                ApiInfo apiInfo = new ApiInfo("My Apps API Title", "My Apps APIDescription", "My Apps API terms ofservice",  
                        "My Apps API ContactEmail", "My Apps API LicenceType", "My Apps API LicenseURL");  
                return apiInfo;  
            }  
        }  

    3.将这个类交给spring来进行管理

    <bean class="cn.brandwisdom.roomVouchers.swagger.SwaggerConfig"/> 

    4.通过注解的方式,让swagger能够知道我们接口对应的功能说明

        @Controller  
        @RequestMapping(value = "/user")  
        @Api(value = "user")  
        public class UserController {  
          
        /**  
         * 根据用户名获取用户对象  
         * @param name  
         * @return  
         */  
        @RequestMapping(value="/name/{name}", method = RequestMethod.GET)  
        @ResponseBody  
        @ApiOperation(value = "根据用户名获取用户对象", httpMethod = "GET", response = ApiResult.class, notes = "根据用户名获取用户对象")  
        public ApiResult getUserByName(@ApiParam(required = true, name = "name", value = "用户名") @PathVariable String name) throws Exception{  
            UcUser ucUser = ucUserManager.getUserByName(name);  
          
            if(ucUser != null) {  
                ApiResult<UcUser> result = new ApiResult<UcUser>();  
                result.setCode(ResultCode.SUCCESS.getCode());  
                result.setData(ucUser);  
                return result;  
            } else {  
                throw new BusinessException("根据{name=" + name + "}获取不到UcUser对象");  
            }  
        }  
          
        }  

    说明:@API(value="user")这个是用来分组的,(不过貌似不写也可以,会自动根据controller来进行分组),@ApiOperation注解对这个方法进行了说明,@ApiParam注解对方法参数进行了说明。

    4.Swagger-UI配置

            Swagger扫描解析得到的是一个json文档,对于用户不太友好。下面介绍swagger-ui,它能够友好的展示解析得到的接口说明内容。

      从https://github.com/swagger-api/swagger-ui 获取其所有的 dist 目录下东西放到需要集成的项目里,本文放入 src/main/webapp/api/ 目录下(也可以放到其它目录下)。


      修改index.html文件,默认是从连接http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON,这里需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式,{}中的值根据自身情况填写。比如我的url值为:http://localhost:8080/vouchers/api-docs

            这里最好新建一个src/main/webapp/api-docs/目录,用于程序生成接口对就的json文件,我看网上的人都没有手动建,但是我的没有自动生成,如果你们自动生成了,可以跳过这一步。 

      因为swagger-ui项目都是静态资源,restful形式的拦截方法会将静态资源进行拦截处理,所以在springmvc配置文件中需要配置对静态文件的处理方式(我这里对目录下所有文件全部放行了)。

    <mvc:resources mapping="/api/**" location="/api/" /> 

    OK!大功告成,打开浏览器直接访问swagger目录下的index.html文件,即可看到接口文档说明了。注意访问地址哦!我的访问地址是:http://localhost:8080/vouchers/api/,注意,如果你web.xml没有配置默认欢迎页面,你要加index.html访问。


    项目中遇到了如下问题,参考了http://www.cnblogs.com/xmplatform/p/5785065.html

     

    1、如何汉化/显示中文

    swagger-ui本身是支持多语言的,在index.html中有这么一段代码:

    <!-- Some basic translations -->
      <!-- <script src='lang/translator.js' type='text/javascript'></script> -->
      <!-- <script src='lang/ru.js' type='text/javascript'></script> -->
      <!-- <script src='lang/en.js' type='text/javascript'></script> -->
    

     大家只需要把注释打开,同时加入对应的中文js即可,最终修改如下:

    <!-- Some basic translations -->
      <script src='lang/translator.js' type='text/javascript'></script>
      <script src='lang/zh-cn.js' type='text/javascript'></script>
      <!-- <script src='lang/en.js' type='text/javascript'></script> -->
    

    2、在swagger-ui中默认的参数的Content Type是application/json,测试时发现后台参数没有接收到值,怎么办?

    img

    大家可能会问,Content Type是application/json有什么影响,为什么要修改为其他呢?这里就要涉及到springMVC中将请求传递过来的参数注入到Controller方法对应对象的原理了,具体知识大家可以搜索一下,这个不是本文重点我就不多讲了,其实我们通常写的Controller方法,默认的Content Type其实是application/x-www-form-urlencoded,而swagger中参数的默认Content Type是application/json,这样就会导致使用swagger测试时,提交到Controller方法的对应参数无法正确注入。

     

    • 那么,该如何处理呢,能改成其他吗?

    其实在swagger-ui的Issues中有人提到过,https://github.com/swagger-api/swagger-ui/issues/658,解决的办法就是要设置consumes这个东东。

    • 解决办法找到了,那consumes在哪里设置呢?

    答案就是在@ApiOperation这个注解里面进行设置,将consumes修改为“application/x-www-form-urlencoded”即可,例如:

     

    @ApiOperation(value="接口说明(测试)",httpMethod="GET",consumes="application/x-www-form-urlencoded",notes="在没有会话、没有签名的情况下,进入方法体")
    

     

    img

    • 那在什么情况下,参数的Content Type才是application/json呢?

    当你的参数加了@RequestBody注解的时候,表示此参数接收的是json数据,这个时候你就可以将consumes写为application/json了

    3、想要知道ApiOperation注解中httpMethod等参数都能写哪些值?

    这个看api文档吧,提供一个地址给大家:http://docs.swagger.io/swagger-core/apidocs/com/wordnik/swagger/annotations/ApiOperation.html

     

  • 相关阅读:
    A1023 Have Fun with Numbers (20分)(大整数四则运算)
    A1096 Consecutive Factors (20分)(质数分解)
    A1078 Hashing (25分)(哈希表、平方探测法)
    A1015 Reversible Primes (20分)(素数判断,进制转换)
    A1081 Rational Sum (20分)
    A1088 Rational Arithmetic (20分)
    A1049 Counting Ones (30分)
    A1008 Elevator (20分)
    A1059 Prime Factors (25分)
    A1155 Heap Paths (30分)
  • 原文地址:https://www.cnblogs.com/arctictern/p/7498838.html
Copyright © 2011-2022 走看看