springfox整合SpringMVC

swagger用於定義API文檔。
1. 好處：
前後端分離開發
API文檔非常明確
測試的時候不需要再使用URL輸入瀏覽器的方式來訪問Controller
傳統的輸入URL的測試方式對於post請求的傳參比較麻煩（當然，可以使用postman這樣的瀏覽器插件）

springfox基於swagger2，兼容老版本

以前的版本是swagger + springmvc，現在springfox中整合了swagger-ui，不需要再引入swagger-ui的靜態文件；

1.添加支持的jar：

classmate-1.3.3.jar
guava-19.0.jar
jackson-annotations-2.8.4.jar
jackson-core-2.8.7.jar
jackson-databind-2.8.7.jar
slf4j-api-1.7.24.jar
spring-plugin-core-1.2.0.RELEASE.jar
spring-plugin-metadata-1.2.0.RELEASE.jar
springfox-core-2.6.1.jar
springfox-schema-2.6.1.jar
springfox-spi-2.6.1.jar
springfox-spring-web-2.6.1.jar
springfox-swagger-common-2.6.1.jar
springfox-swagger-ui-2.6.1.jar
springfox-swagger2-2.6.1.jar
swagger-annotations-1.5.10.jar
swagger-models-1.5.10.jar
2.添加com.chensan.config.Swagger2Config.java

package com.chensan.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

//@Configuration
@EnableSwagger2
public class Swagger2Config {
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
			.apiInfo(apiInfo())
			.select()
			.apis(RequestHandlerSelectors.basePackage("com.chensan.api"))
			.paths(PathSelectors.any())
			.build();
	}

	private ApiInfo apiInfo() {
		Contact contact = new Contact("chenhf", "http://blog.csdn.net/qinshijangshan", "[email protected]");

		return new ApiInfoBuilder()
			.title("OAuth 2.0 RESTful APIs")
			.description("OAuth2.0 RESTFul API 文檔")
			.termsOfServiceUrl("http://blog.csdn.net/qinshijangshan")
			.license("© 2017-2025 chenhf. All rights reserved.")
			.contact(contact)
			.version("1.0")
			.build();
	}
}

下面添加測試功能的內容

User.java

package com.chensan.api.test.po;

public class User {
    private int userId;
    private String name;
    private int age;

    public User() {
    }

    public User(int userId, String name, int age) {
        this.userId = userId;
        this.name = name;
        this.age = age;
    }

    public String getName() {
        return name;
    }

    public User setName(String name) {
        this.name = name;
        return this;
    }

    public int getAge() {
        return age;
    }

    public User setAge(int age) {
        this.age = age;
        return this;
    }

    public int getUserId() {
        return userId;
    }

    public User setUserId(int userId) {
        this.userId = userId;
        return this;
    }
}

Result.java

package com.chensan.api.test.vo;

import java.io.Serializable;

public class Result implements Serializable {
    private static final long serialVersionUID = 1L;

    // 1：成功
    private int code;

    // 返回消息，成功爲“success”，失敗爲具體失敗信息
    private String message;

    // 返回數據
    private Object data;

    public int getCode() {
        return code;
    }

    public void setCode(int code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public Object getData() {
        return data;
    }

    public void setData(Object data) {
        this.data = data;
    }

    @Override
    public String toString() {
        return "Result{" +
                "code=" + code +
                ", message='" + message + '\'' +
                ", data=" + data +
                '}';
    }
}

UserController

package com.chensan.api.test;

import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
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 org.springframework.web.bind.annotation.RestController;

import com.chensan.api.test.po.User;
import com.chensan.api.test.vo.Result;

import javax.servlet.http.HttpServletRequest;

@RestController
@RequestMapping("/userTest")
public class UserController {

    @ApiOperation(value = "根據用戶id查詢用戶信息", httpMethod = "GET", produces = "application/json")
    @ApiResponse(code = 200, message = "success", response = Result.class)
    @ResponseBody
    @RequestMapping(value = "queryUserById", method = RequestMethod.GET, produces = "application/json")
    public Result queryUserById(@ApiParam(name = "userId", required = true, value = "用戶Id") @RequestParam("userId") int userId, HttpServletRequest request) {
        User user = new User(userId, "chenhf", 25);
        Result result = new Result();
        result.setCode(0);
        result.setData(user);
        result.setMessage("success");
        return result;
    }
}

3.在springmvc-config.xml中添加

<bean class="com.chensan.config.Swagger2Config" />

<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html" />
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**" />

訪問：ip:port/{context-path}/swagger-ui.html
實例：http://localhost/bphss-sample/swagger-ui.html
訪問到springfox-swagger-ui-2.6.1.jar/META-INF/resources下的swagger-ui.html
頁面出現黃綠色背景即springfox + swagger2組合的API框架配置成功。
注：swagger + springmvc繼承需要導入swagger-ui的靜態文件到項目中。
springfox + swagger2則不需要，在springfox-swagger-ui-2.6.1.jar中已經包含swagger-ui的源碼，並在springmvc-config.xml中引入。

關於Springfox + swagger2的繼承可參考： http://blog.csdn.net/u014231523/article/details/54411026

相關問題可參考： http://m.w2bc.com/article/229092

前面有個朋友說按我的配置報錯：報錯http://localhost:8080/onemap/swagger-resources/configuration/ui 404 ()；那麼顯然是路徑問題了，我前面用的springfox-2.6.1的版本沒問題，後來用最新版的springfox-2.9.0也出現了問題（我這裏是後面補得記錄，懶得回溯去截圖出來。swagger-ui.html訪問下就知道問題了）。

在springmvc配置文件設置：