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，更高版本有更多特性，你們按各自狀況選擇版本吧