SpringBoot整合Swagger快速構建REST-API並生成優美的API文檔

上一篇《簡單搭建SpringBoot項目》講了簡單的搭建SpringBoot 項目，而 SpringBoot 和 Swagger-ui 搭配在持續交付的前後端開發中意義重大，Swagger 規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務，對調用方而言非常直觀，接口也可以點擊try it out!按鈕 進行調試，在實際開發中大大增加了開發效率。點擊可瞭解更多 swagger 相關信息swagger-ui官網

pom.xml中增加：

        <!-- 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.5.0</version>
        </dependency>

SwaggerConfig.java：

package com.example.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.async.DeferredResult;
import springfox.documentation.builders.ApiInfoBuilder;
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 static springfox.documentation.builders.PathSelectors.regex;

/**
 * Created by shuai on 2017/5/22.
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 可以定義多個組，比如本類中定義把test和demo區分開了
     */
    @Bean
    public Docket testApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("test")
                .genericModelSubstitutes(DeferredResult.class)
//                .genericModelSubstitutes(ResponseEntity.class)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(true)
                .pathMapping("/")// base，最終調用接口後會和paths拼接在一起
                .select()
                .paths((regex("/api/test/.*")))//過濾的接口
                .build()
                .apiInfo(testApiInfo());
    }

    @Bean
    public Docket demoApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("demo")
                .genericModelSubstitutes(DeferredResult.class)
//              .genericModelSubstitutes(ResponseEntity.class)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(false)
                .pathMapping("/")
                .select()
                .paths((regex("/api/demo/.*")))//過濾的接口
                .build()
                .apiInfo(demoApiInfo());
    }

    private ApiInfo testApiInfo() {
        return new ApiInfoBuilder()
                .title("Test 類型 API")//大標題
                .description("這是 Test 類型 API 描述")//詳細描述
                .version("1.0")//版本
                .termsOfServiceUrl("NO terms of service")
                .contact(new Contact("shuai", "http://www.jianshu.com/u/07b9ae164f95", "[email protected]"))//作者
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }

    private ApiInfo demoApiInfo() {
        return new ApiInfoBuilder()
                .title("Demo 類型 API")//大標題
                .description("這是 Demo 類型 API 描述")//詳細描述
                .version("1.0")//版本
                .termsOfServiceUrl("NO terms of service")
                .contact(new Contact("shuai", "http://www.jianshu.com/u/07b9ae164f95", "[email protected]"))//作者
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }
}

此時啓動 SpringBoot 工程，在瀏覽器輸入 http://localhost:8080/swagger-ui.html 即可看見：

在 SwaggerConfig.java 文件中配置了掃描接口的路徑，只有符合標準的接口才會顯示出來，

常見swagger註解一覽與使用

• 最常用的5個註解
  @Api：修飾整個類，描述Controller的作用
  @ApiOperation：描述一個類的一個方法，或者說一個接口
  @ApiParam：單個參數描述
  @ApiModel：用對象來接收參數
  @ApiProperty：用對象接收參數時，描述對象的一個字段
• 其它若干
  @ApiResponse：HTTP響應其中1個描述
  @ApiResponses：HTTP響應整體描述
  @ApiIgnore：使用該註解忽略這個API

下面創建符合規範的接口：
TestController.java:

package com.example.controller;

import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.http.MediaType;
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;

/**
 * Created by shuai on 2017/5/22.
 */
@Controller
@RequestMapping("/api/test")
public class TestController {

    @ResponseBody
    @RequestMapping(value = "/user", method= RequestMethod.POST, produces= MediaType.APPLICATION_JSON_VALUE)
    @ApiOperation(value="獲取user", notes="根據id獲取User的接口")
    public String getUser(
            @ApiParam(required=true, name="id", value="主鍵id") @RequestParam(name = "id", required=true) String id
            ){
        return "success";
    }
}

當對象作爲入參時，需要創建一個對象，對象中要用到上面提到的@ApiModel @ApiModelProperty 等註解：
UserVo.java:

package com.example.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * Created by shuai on 2017/5/22.
 */
@ApiModel(description = "用戶的對象")
public class UserVo {

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("年齡")
    private Integer age;

    @ApiModelProperty("性別")
    private String sex;
    
    //
    Get And Set Method...()

DemoController.java:

package com.example.controller;

import com.example.vo.UserVo;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;
import java.util.ArrayList;
import java.util.List;

/**
 * Created by shuai on 2017/5/21.
 */
@Controller
@RequestMapping(value = "/api/demo")
public class DemoController {

    @ResponseBody
    @RequestMapping(value = "/getUser", method = RequestMethod.POST)
    @ApiOperation(value="測試getUser", notes="getUser詳細說明", response = UserVo.class)
    public UserVo getCount(
            @ApiParam( required = true, name = "user", value = "入參爲User對象") @RequestBody UserVo user
    ) {
        return user;
    }

}

這樣一個簡單的 SpringBoot 和Swagger-ui 結合的工程就完成了，下面啓動運行：

github地址：Spring Boot 教程、技術棧、示例代碼