SpringMVC集成springfox-swagger2自動生成接口文檔

本節內容：

• 什麼是Swaggger
• Springfox與Swagger的關係 
• SpringMVC集成springfox-swagger2

 

1、什麼是Swaggger

Swagger是一個流行的API開發框架，這個框架以「開放API聲明」（OpenAPI Specification，OAS）爲基礎，對整個API的開發週期都提供了相應的解決方案，是一個很是龐大的項目（包括設計、編碼和測試，幾乎支持全部語言）。

 

2、Springfox與Swagger的關係 

OSA自己是一個API規範，它用於描述一整套API接口，包括一個接口是GET仍是POST請求啊，有哪些參數哪些header啊，都會被包括在這個文件中。它在設計的時候一般是YAML格式，這種格式書寫起來比較方便，而在網絡中傳輸時又會以json形式居多，由於json的通用性比較強。

因爲Spring的流行，Marty Pitt編寫了一個基於Spring的組件swagger-springmvc，用於將swagger集成到springmvc中來。而springfox則是從這個組件發展而來，同時springfox也是一個新的項目，本文使用的是其中的一個組件springfox-swagger2。

若是想要集成swagger-springmvc就相對麻煩一點，由於要把它的靜態文件copy到本身的項目中。springfox-swagger2依然是依賴OSA規範文檔，也就是一個描述API的json文件，而這個組件的功能就是幫助咱們自動生成這個json文件，咱們會用到的另一個組件springfox-swagger-ui就是將這個json文件解析出來，用一種更友好的方式呈現出來。

 

3、SpringMVC集成springfox-swagger2

1. 添加依賴的jar包

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

　　

2. spring-mvc.xml中添加映射靜態的配置

<mvc:default-servlet-handler />　

 

3. 配置文件

在源碼包裏建一個config目錄，並在裏面建立一個SwaggerConfig.java文件，這是一個spring的配置文件，因此位置和文件名都影響不大。

SwaggerConfig.java

package com.spring.learn.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;

/**
 * Created by jkzhao on 1/19/18.
 */
@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.spring.learn.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring 中使用Swagger2構建RESTful APIs")
                .termsOfServiceUrl("http://www.cnblogs.com/zhaojiankai/")
                .description("springmvc swagger2")
                .contact(new Contact("zhaojiankai", "http://www.cnblogs.com/zhaojiankai/", "743833196@qq.com"))
                .version("1.1")
                .build();
    }
}

這個SwaggerConfig類有四個註解，其中，@Configuration是Spring的註解，而@EnableSwagger2則是用來啓動Swagger支持，表示這是一個Spring Swagger的配置文件。

以後，定義了一個Bean方法createRestApi，Spring中名字並不重要，重要的是它返回一個Docket類，DocumentationType.SWAGGER_2做爲Docket構造方法的參數，指定了所用的swagger版本2.0，官網上已經在預告3.0版本了。而以後的apiInfo則是調用接下來的apiInfo函數，來建立Docket的信息。apiInfo函數採用ApiInfoBuilder來建立ApiInfo類。

 

而後運行項目，在瀏覽器輸入：http://{ip}:{port}/{projectname}/swagger-ui.html

它會把按照controller，把全部的接口都加載進來。 

個人目錄結構如圖： 

而後，就是接口名稱和參數的說明：
經常使用註解：

• @Api()用於類名
• @ApiOperation()用於方法名
• @ApiParam()用於參數說明
• @ApiModel()用於實體類
• @ApiModelProperty用於實體類屬性

 更詳細的說明請參見官方註解說明文檔

【示例】：

ApiController.java

@Controller
@RequestMapping("/api")
@Api(value = "api接口", description="用戶相關操做")
public class ApiController {
    @Autowired
    private UserService userService;

    @RequestMapping(value = "/user", method = {RequestMethod.GET})
    @ApiOperation(value = "用戶查詢服務", notes = "根據傳過來的user_id來查詢用戶")
    public String getUserById(@ApiParam(value = "用戶id") String user_id, ModelMap map){
        User user =  userService.getUserById(user_id);
        map.put("user", user);

        return "success";
    }

}

User.java

@ApiModel(value = "用戶")
public class User {
    private String user_id;

    @ApiModelProperty(value = "用戶名")
    private String user_name;

    @ApiModelProperty(value = "密碼")
    private String password;
    ...

從新運行起項目，訪問效果以下：