swagger + spring mvc 实现rest 接口代码与api 同步维护，更新

概述

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

        简单的说，就是将res接口的文档解释和代码更新同步，不须要维护代码和文档，形成api文档跟不上代码的速度，api文档更新不及时，还耗费资源维护。

springfox原理

       springfox的原理，是经过解析springmvc的handlerMapping得到接口的信息，生存api文档，使用这种方式不须要太多的学习成本。只须要一些spring 配置便可。开发人员除了一两个注解，不须要了解太多。

swagger springfox基本信息

       swagger  http://swagger.io/

       springfox https://springfox.github.io/springfox/

       swagger 能够和不少技术整合在一块儿，具体的能够在 swagger -tools菜单下面找  http://swagger.io/open-source-integrations/

       springfox 原名 swagger-springMvc，在2以前的版本和2以后的版本包路径不同的，由于工做中使用的spring mvc版本为3.2.5，因此决定使用 0.8.8版本。其余版本的可使用以上两个网站查找。

依赖

compile "com.mangofactory:swagger-springmvc:0.8.8"
compile 'org.ajar:swagger-spring-mvc-ui:0.2'

 

配置

配置分两部分，在xml中

    <!-- swagger springfox -->
    <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
    <!-- 使用 SwaggerSpringMvcPlugin 方式 -->
    <bean class="org.my.swaggerconfig.SwaggerConfig" />

    <mvc:resources mapping="*.html" location="/" />
    <mvc:default-servlet-handler />

java SwaggerSpringMvcPlugin文件

@Configuration
@EnableSwagger
public class SwaggerConfig {
     private SpringSwaggerConfig springSwaggerConfig;

       /**
        * Required to autowire SpringSwaggerConfig
        */
       @Autowired
       public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
          this.springSwaggerConfig = springSwaggerConfig;
       }

       /**
        * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc framework - allowing for multiple
        * swagger groups i.e. same code base multiple swagger resource listings.
        */
       @Bean
       public SwaggerSpringMvcPlugin customImplementation(){
          return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                  .includePatterns(".*.*");
       }
}

 SwaggerConfig.java 能够作更多事情，如设置全局环境（过滤参数等）

swagger-ui

ui: http://localhost:8080/springfox/index.html

api :http://localhost:8080/springfox/api-docs

title 等信息能够设置的。

其余信息能够参看官方网站，github，更高版本有更多特性，你们按各自状况选择版本吧