一、pom.xml依賴管理

   <!-- swagger-springmvc -->
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-models</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.wordnik</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.3.11</version>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>15.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml</groupId>
<artifactId>classmate</artifactId>
<version>1.1.0</version>
</dependency>
<dependency>
<groupId>cglib</groupId>
<artifactId>cglib</artifactId>
<version>2.2.2</version>
</dependency>
<!-- swagger-springmvc dependencies -->

二、Swagger配置，自定義一個SwaggerConfig檔案

@Configuration
@EnableSwagger 
public class SwaggerConfig {

@Autowired
private SpringSwaggerConfig springSwaggerConfig;
@Resource
private Boolean  swaggerEnable;//通過ApplicationContent.xml 配置檔案注入swaggerEnable變數。
    /**
     * Required to autowire SpringSwaggerConfig
     */

    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
    {
        this.springSwaggerConfig = springSwaggerConfig;
    }


    @Bean
    public SwaggerSpringMvcPlugin customImplementation()
    {
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo())
                .enable(swaggerEnable)//通過配置pom.xml中swaggerEnable變數true,false實現不同生產環境中是否啟用Swagger.
                .includePatterns(".*");
    }

private ApiInfo apiInfo()
    {
        ApiInfo apiInfo = new ApiInfo(
                "My Apps API Title",
                "My Apps API Description",
                "My Apps API terms of service",
                "My Apps API Contact Email",
                "My Apps API Licence Type",
                "My Apps API License URL");
        return apiInfo;
    }
}

三、在ApplicationContent.xml配置

   <mvc:annotation-driven/> 

   .....

   .....
   <!-- swagger檔案路徑 -->
   <bean id="swaggerEnable" class="java.lang.Boolean">
     <constructor-arg><value>${swaggerEnable}</value></constructor-arg>
   </bean>
   
   <bean class="com.cn.web.controller.SwaggerConfig" />

四、Controller介面，配置@ApiOperation

  /**
 * 介面
 * @throws JsonProcessingException 
 */
@ApiOperation(value = "獲取某球隊戰績", httpMethod = "GET", notes = "獲取某球隊戰績")
@RequestMapping(value="/test/getResult",produces = "application/json;charset=UTF-8")
public @ResponseBody String getResult(@RequestParam("matchnum") String xid) throws JsonProcessingException{
Map resultMap = new HashMap();
ErrorCode err = ErrorCode.success;
long start=System.currentTimeMillis();
JSONObject jsonObject=null;;
try {
jsonObject = service.getResult(xid);
if(jsonObject==null || jsonObject.isEmpty()){
err=ErrorCode.notHaveRecord;
jsonObject =new  JSONObject();
}
long end=System.currentTimeMillis();
logger.info("介面，用時："+(end-start));
resultMap.put("result", jsonObject);
} catch (ProcessException e) {
logger.error("介面異常", e);
}finally {
resultMap.put("errorCode", err.value);
resultMap.put("message", err.memo);
}
return JSON.toJSONString(resultMap);
}

五、Swagger掃描解析得到的是一個json文件，對於使用者不太友好。下面介紹swagger-ui，它能夠友好的展示解析得到的介面說明內容。

從https://github.com/swagger-api/swagger-ui 獲取其所有的 dist 目錄下東西放到需要整合的專案裡，本文放入 src/main/webapp/WEB-INF/swagger/ 目錄下。

  修改swagger/index.html檔案，預設是從連線http://petstore.swagger.io/v2/swagger.json獲取 API 的 JSON，這裡需要將url值修改為http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根據自身情況填寫。比如我的url值為：http://localhost:8083/arrow-api/api-docs

  因為swagger-ui專案都是靜態資源，restful形式的攔截方法會將靜態資源進行攔截處理，所以在springmvc配置檔案中需要配置對靜態檔案的處理方式。

//所有swagger目錄的訪問，直接訪問location指定的目錄
<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>

  OK！大功告成，開啟瀏覽器直接訪問swagger目錄下的index.html檔案，即可看到介面文件說明了。注意訪問地址哦！看下圖：