springMvc+swagger整合例子

　　Swagger 是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API與接口方法，參數等保存同步，大大減少了接口開發人員的工作量.這個例子是我本地運行正常的，完整demo在文章最后。

　　第一步：在pom.xml引入相關jar 

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>
        
        <dependency>  
            <groupId>com.fasterxml.jackson.core</groupId>  
            <artifactId>jackson-core</artifactId>  
            <version>2.8.0</version>  
        </dependency>  
        <dependency>  
            <groupId>com.fasterxml.jackson.core</groupId>  
            <artifactId>jackson-databind</artifactId>  
            <version>2.6.3</version>  
        </dependency>  
        <dependency>  
            <groupId>com.fasterxml.jackson.core</groupId>  
            <artifactId>jackson-annotations</artifactId>  
            <version>2.6.3</version>  
        </dependency>  

　　第二步：配置spring-servlet.xml

<!-- 激活@controller模式 -->
    <mvc:annotation-driven />
    <!-- 配置包掃描位置（會在此包下掃描@controller控制器） -->
    <context:component-scan base-package="com.scan,com.bean" />
<!--  swagger靜態文件路徑 -->
<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/" cache-period="31556926"/>
    <mvc:default-servlet-handler />
    <bean class="com.scan.config.SwaggerConfig" /> 

　　第三步：編寫SwaggerConfig

　　　　

package com.scan.config;
   
import com.google.common.base.Predicate;

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

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;

import java.util.List;

import static com.google.common.base.Predicates.or;
import static com.google.common.collect.Lists.newArrayList; 
 
@Configuration
@EnableSwagger2
@ComponentScan(basePackages = {"com.scan.controller"})   
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Bean
    public Docket customDocket() {
        //
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("老王", "https://www.baidu.me", "[e-mail]");
        return new ApiInfo("Blog前台API接口",//大標題 title
                "Swagger測試demo",//小標題
                "0.0.1",//版本
                "www.baidu.com",//termsOfServiceUrl
                contact,//作者
                "Blog",//鏈接顯示文字
                "https://www.baidu.me"//網站鏈接
        );
    }
    
      
}

　　第四步：控制層的配置

　　

@Controller
@RequestMapping("/userController")
@Api(tags = "二：用戶信息") //swagger分類標題注解
public class UserController {

    @RequestMapping(value = "/listCompound", method = RequestMethod.GET)
    @ResponseBody
　　//swagger返回值注解
    @ApiResponses(value = {
            @ApiResponse(code = 500, message = "系統錯誤"),
            @ApiResponse(code = 200, message = "0 成功,其它為錯誤,返回格式：{code:0,data[{}]},data中的屬性參照下方Model", response = UserVo.class) })
    @ApiOperation(httpMethod = "GET", value = "個人信息")//swagger 當前接口注解
    public String listCompound(
            @ApiParam(required = true, name = "start", value = "start") int start,
            int limit,
            @ApiParam(required = false, name = "userName", value = "名稱模糊查詢") String userName) {
        List<UserVo> data = new ArrayList<UserVo>();
        String msg = data.size() > 0 ? "" : "沒有查詢到相關記錄";
        Result result = new Result();
        result.setMsg(msg);
        result.setCode(0);
        result.setData(data);
        return JSONObject.toJSONString(result);
    }

　　第五步：下載swaggerUi,將下載后的文件解壓，將dist目錄下的文件，復制到webapp下的swagger目錄中(這個目錄的名字自定義，但要和spring-servert.xml中(<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/") 的名稱要一致,修改index.html中文檔加載的地址.

window.onload = function() {
  
  // Build a system
  const ui = SwaggerUIBundle({
    //url: "http://petstore.swagger.io/v2/swagger.json",
    url:"http://127.0.0.1:8080/swagger-spring/v2/api-docs.do",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })

　　如果以上配置正確，在瀏覽器中輸入http://127.0.0.1:8080/swagger-spring/swagger/index.html，將會出現如下界面:

　　

 

　swagger注解說明

 　　 1、與模型相關的注解,用在bean上面

　　　　@ApiModel：用在bean上，對模型類做注釋；

　　　　@ApiModelProperty：用在屬性上，對屬性做注釋

　　2、與接口相關的注解

　　　　@Api：用在controller上，對controller進行注釋；

　　　　@ApiOperation：用在API方法上，對該API做注釋，說明API的作用；

　　　　@ApiImplicitParams：用來包含API的一組參數注解，可以簡單的理解為參數注解的集合聲明； 

　　　　@ApiImplicitParam：用在@ApiImplicitParams注解中，也可以單獨使用，說明一個請求參數的各個方面，該注解包含的常用選項有：

　　　　　　paramType：參數所放置的地方，包含query、header、path、body以及form，最常用的是前四個。

　　　　　　name：參數名；

　　　　　　dataType：參數類型，可以是基礎數據類型，也可以是一個class；

　　　　　　required：參數是否必須傳；

　　　　　　value：參數的注釋，說明參數的意義；

　　　　　　defaultValue：參數的默認值；

　　　　

　　　 @ApiResponses：通常用來包含接口的一組響應注解，可以簡單的理解為響應注解的集合聲明；

　　　 @ApiResponse：用在@ApiResponses中，一般用於表達一個響應信息

　　　　　　code：即httpCode，例如400 

　　　　　　message：信息，例如"操作成功"

　　　　　　response = UserVo.class  這里UserVo是一個配置了@ApiModel注解的對像，該是對像屬性已配置 @ApiModelProperty,swagger可以通過這些配置，生　成接口返回值

　　

　　注意事項:

1. 為了在swagger-ui上看到輸出，至少需要兩個注解：@Api和@ApiOperation
2. 即使只有一個@ApiResponse，也需要使用@ApiResponses包住
3. 對於@ApiImplicitParam的paramType：query、form域中的值需要使用@RequestParam獲取， header域中的值需要使用@RequestHeader來獲取，path域中的值需要使用@PathVariable來獲取，body域中的值使用@RequestBody來獲取，否則可能出錯；而且如果paramType是body，name就不能是body，否則有問題，與官方文檔中的“If paramType is "body", the name should be "body"不符。

　　完整demo下載地址:https://github.com/jlq023/spring_swaggerDemo