Swagger是一個rest api文件解決方案。對於有手機端app的企業來說，維護一套api文件是一件麻煩的事情，app端和後端人員的溝通將浪費過多時間。如果人數不夠，單元測試也是麻煩的事情。Swagger是一個很好的解決方案。

        Swagger的整合準備分兩篇文章簡紹

        1、與傳統spring整合

        2、與spring-boot整合

        spring-boot相當方便，還是建議大家新的工程都用spring-boot

        pom

swagger2開始已經融合到springfox中了，因此依賴如下：

<!--springfox依賴-->
		<dependency>
		    <groupId>com.mangofactory</groupId>
		    <artifactId>swagger-springmvc</artifactId>
		    <version>1.0.2</version>
		</dependency>
		<!--jackson依賴-->
		<dependency>
		    <groupId>com.fasterxml.jackson.core</groupId>
		    <artifactId>jackson-databind</artifactId>
		    <version>2.4.2</version>
		</dependency>
		<!--靜態頁面依賴的webjar-->
		<dependency>
		    <groupId>org.webjars.bower</groupId>
		    <artifactId>swagger-ui</artifactId>
		    <version>2.1.8-M1</version>
		</dependency>
		<dependency>
		    <groupId>com.google.guava</groupId>
		    <artifactId>guava</artifactId>
		    <version>15.0</version>
		</dependency>
		 <!-- springmvc annotation-driven 所需包 -->
        <dependency>
		    <groupId>org.hibernate</groupId>
		    <artifactId>hibernate-validator</artifactId>
		</dependency>
 

        配置

        既然現在都是用spring4，那就別用xml來配置了，這裡提供java config

import javax.servlet.ServletContext;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.paths.RelativeSwaggerPathProvider;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

@Configuration
@EnableWebMvc
@EnableSwagger
public class SpringfoxConfig extends WebMvcConfigurerAdapter {

	public static String PROJECT_NAME;
    
    @Autowired
    private ServletContext servletContext;

    static {
        PROJECT_NAME = "xxx的api";
    }

    private SpringSwaggerConfig springSwaggerConfig;

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

    /**
     * 鏈式程式設計 來定製API樣式
     * 後續會加上分組資訊
     *
     * @return
     */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation() {
    	
    	RelativeSwaggerPathProvider swaggerPathProvider = new RelativeSwaggerPathProvider(servletContext);
    	
    	swaggerPathProvider.setApiResourcePrefix("rest");
    	
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo())
                .includePatterns(".*")
                .pathProvider(swaggerPathProvider)
                .apiVersion("0.0.1");
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                PROJECT_NAME + " API",
                PROJECT_NAME + " xxxAPI文件",
                "http://localhost/api-doc/index.html",
                "
 
[email protected]",
                "xxx",
                "xxx"
        );
        return apiInfo;
    }
	
}

注意，通過RelativeSwaggerPathProvider來設定相對路徑，比如你的rest介面路徑都是以/rest開頭，那麼就需要通過該類進行設定。此外，還有一個絕對地址的設定類。

給一個比較全面的配置地址

http://grepcode.com/file/repo1.maven.org/maven2/com.mangofactory/swagger-springmvc/0.8.7/com/mangofactory/swagger/configuration/SpringSwaggerConfig.java#SpringSwaggerConfig.0servletContext

swagger-ui

下載相應版本的swagger-ui，比如這裡用swaggr-ui 2.1.5。如果版本不對，那麼將找不到rest api

將dist資料夾放到web容器中。如果前後端沒有分離，放到webroot或webapp下。如果使用nginx進行前後端分離，那麼將dist放到相應的資料夾中，比如我建立一個

api-doc資料夾，並把dist檔案中的內容放入其中。

修改index.html檔案，將請求路徑換成rest介面根路徑+api-docs，比如：http://localhost/ecouponApi/rest/api-docs

加入header資訊

大部分情況，手機端的身份驗證需要通過http header來進行，為了使用header，需要在介面方法上加上如下注釋

 @ApiImplicitParams({
        @ApiImplicitParam(paramType="header", name = "xytkj-auth-token", value = "token", required = true, dataType = "String")
    })

@ApiImplicitParam和@ApiParam

@ApiImplicitParam的query型別引數可以通過request獲取，和@RequestParam為獨立的引數。@ApiParam僅僅註解request上的引數

比如：以下配置是錯誤的

 @ResponseBody
    @RequestMapping(value = "/loginout", method = RequestMethod.POST)
    @ApiOperation(value="退出登入", notes="退出登入")
    @ApiImplicitParams({
        @ApiImplicitParam(paramType="header", name = "xytkj-auth-token", value = "令牌", required = true, dataType = "String"),
        @ApiImplicitParam(paramType="query", name = "phone", value = "電話號碼", required = true, dataType = "String"),
        @ApiImplicitParam(paramType="query", name = "sign", value = "簽名", required = true, dataType = "String")
    })
    public void loginout(
    		@RequestParam("phone") String phone,
            @RequestParam("sign") String sign,  
            HttpServletRequest request,
            HttpServletResponse response) throws SysException {

}

 @ResponseBody
    @RequestMapping(value = "/loginout", method = RequestMethod.POST)
    @ApiOperation(value="退出登入", notes="退出登入")
    @ApiImplicitParams({
        @ApiImplicitParam(paramType="header", name = "xytkj-auth-token", value = "令牌", required = true, dataType = "String")
    })
    public void loginout(
    		@ApiParam(required=true,value="電話",name="phone")
    		@RequestParam("phone") String phone,
    		@ApiParam(required=true,value="簽名",name="sign")
            @RequestParam("sign") String sign,  
            HttpServletRequest request,
            HttpServletResponse response) throws SysException {

}

訪問api文件

地址為：swagger-ui的index.html

最後看下效果