Spring3 MVC中使用Swagger生成API文檔

來自： http://blog.csdn.net/jia20003/article/details/50700736

Spring3 MVC中使用Swagger生成API文檔

一：Swagger介紹

Swagger是當前最好用的Restful API文檔生成的開源項目，通過swagger-spring項目

實現了與SpingMVC框架的無縫集成功能，方便生成spring restful風格的接口文檔，

同時swagger-ui還可以測試spring restful風格的接口功能。其官方網站為：

http://swagger.io/

二：Swagger集成Spring3 MVC步驟

Swagger集成springMVC步驟大致只有如下幾步：

1.在pom.xml文件中添加swagger相關的依賴

                <!-- swagger API document -->
        <dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-springmvc</artifactId>
            <version>0.6.5</version>
        </dependency>

2.創建classpath路徑下創建一個swagger.properties, 添加如下內容：

documentation.services.version=1.0

documentation.services.basePath=http://localhost:8080/yourcontextpath

3.在springMVC的main-servlet.xml文件添加如下配置

 <context:property-placeholder location="classpath:swagger.properties" />
    <bean id="documentationConfig" class="com.mangofactory.swagger.configuration.DocumentationConfig" />

4.重新打包部署你的項目到WEB服務器，訪問地址

http://localhost:8080/your-contextpath /api-docs即可看到注解生成的API說明

三：常見swagger注解一覽與使用

APIs.@Api

@ApiClass

@ApiError

@ApiErrors

@ApiOperation

@ApiParam

@ApiParamImplicit

@ApiParamsImplicit

@ApiProperty

@ApiResponse

@ApiResponses

@ApiModel

在代碼中使用例子：

import java.util.HashMap;
import java.util.Map;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;

import com.wordnik.swagger.annotations.ApiOperation;

@Controller
@RequestMapping("/api/swagger")
public class SwaggerDemoController {
    private static final Logger logger = LoggerFactory.getLogger(SwaggerDemoController.class);

    @ApiOperation(value = "query api basic information")
    @RequestMapping(value = "/info", method = RequestMethod.GET)
    @ResponseBody
    public Map<String, String> queryAPIInfo() {
        logger.info("查詢更新新版本號");
        Map<String, String> map = new HashMap<String, String>();
        map.put("language", "Java");
        map.put("format", "JSON");
        map.put("tools", "swagger");
        map.put("version", "1.0");
        return map;
    }

    @ApiOperation(value = "query data with parameters")
    @RequestMapping(value = "/data", method = RequestMethod.GET)
    @ResponseBody
    public Map<String, String> queryData(@RequestParam String words) {
        logger.info("查詢更新新版本號");
        Map<String, String> map = new HashMap<String, String>();
        map.put("keyword", words);
        map.put("data", "this is demo data");
        return map;
    }
}

四：運行swagger-ui測試接口

下載swagger-ui的最新版本到本地，改名為swagger-ui，把dist下面的部署到tomcat

或者任何WEB服務器上，啟動后訪問如下地址: http://localhost:8080/swagger-ui

注意把swagger-ui中的index.html中的http://petstore.swagger.io/v2/swagger.json改為

http://localhost:8080/your-contextpath /api-docs保存，然后在啟動WEB服務器，

顯示如下：

展開輸入參數以后，點擊【try it out】即可測試接口，查看返回數據。
注意：加上之后啟動報Bean not found mapping之類的錯誤，請在對應

xml文件中加上如下的配置：

<context:annotation-config />
<mvc:default-servlet-handler />