上一篇《 簡(jiǎn)單搭建SpringBoot項(xiàng)目》講了簡(jiǎn)單的搭建SpringBoot 項(xiàng)目皇型，而 SpringBoot 和 Swagger-ui 搭配在持續(xù)交付的前后端開(kāi)發(fā)中意義重大，Swagger 規(guī)范和完整的框架溶诞，用于生成水由、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)，對(duì)調(diào)用方而言非常直觀宠哄，接口也可以點(diǎn)擊try it out!按鈕 進(jìn)行調(diào)試壹将，在實(shí)際開(kāi)發(fā)中大大增加了開(kāi)發(fā)效率。點(diǎn)擊可了解更多 swagger 相關(guān)信息swagger-ui官網(wǎng)

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 {

    /**
     * 可以定義多個(gè)組毛嫉，比如本類中定義把test和demo區(qū)分開(kāi)了
     */
    @Bean
    public Docket testApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("test")
                .genericModelSubstitutes(DeferredResult.class)
//                .genericModelSubstitutes(ResponseEntity.class)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(true)
                .pathMapping("/")// base诽俯，最終調(diào)用接口后會(huì)和paths拼接在一起
                .select()
                .paths((regex("/api/test/.*")))//過(guò)濾的接口
                .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/.*")))//過(guò)濾的接口
                .build()
                .apiInfo(demoApiInfo());
    }

    private ApiInfo testApiInfo() {
        return new ApiInfoBuilder()
                .title("Test 類型 API")//大標(biāo)題
                .description("這是 Test 類型 API 描述")//詳細(xì)描述
                .version("1.0")//版本
                .termsOfServiceUrl("NO terms of service")
                .contact(new Contact("shuai", "http://www.reibang.com/u/07b9ae164f95", "1119386572@qq.com"))//作者
                .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")//大標(biāo)題
                .description("這是 Demo 類型 API 描述")//詳細(xì)描述
                .version("1.0")//版本
                .termsOfServiceUrl("NO terms of service")
                .contact(new Contact("shuai", "http://www.reibang.com/u/07b9ae164f95", "1119386572@qq.com"))//作者
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }
}

此時(shí)啟動(dòng) SpringBoot 工程，在瀏覽器輸入 http://localhost:8080/swagger-ui.html 即可看見(jiàn)：

Swagger-ui效果圖

在 SwaggerConfig.java 文件中配置了掃描接口的路徑承粤，只有符合標(biāo)準(zhǔn)的接口才會(huì)顯示出來(lái)暴区，

常見(jiàn)swagger注解一覽與使用

• 最常用的5個(gè)注解
  @Api：修飾整個(gè)類仙粱，描述Controller的作用
  @ApiOperation：描述一個(gè)類的一個(gè)方法房交，或者說(shuō)一個(gè)接口
  @ApiParam：?jiǎn)蝹€(gè)參數(shù)描述
  @ApiModel：用對(duì)象來(lái)接收參數(shù)
  @ApiProperty：用對(duì)象接收參數(shù)時(shí)，描述對(duì)象的一個(gè)字段
• 其它若干
  @ApiResponse：HTTP響應(yīng)其中1個(gè)描述
  @ApiResponses：HTTP響應(yīng)整體描述
  @ApiIgnore：使用該注解忽略這個(gè)API

下面創(chuàng)建符合規(guī)范的接口：
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="根據(jù)id獲取User的接口")
    public String getUser(
            @ApiParam(required=true, name="id", value="主鍵id") @RequestParam(name = "id", required=true) String id
            ){
        return "success";
    }
}

當(dāng)對(duì)象作為入?yún)r(shí)伐割，需要?jiǎng)?chuàng)建一個(gè)對(duì)象负溪，對(duì)象中要用到上面提到的@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 = "用戶的對(duì)象")
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="測(cè)試getUser", notes="getUser詳細(xì)說(shuō)明", response = UserVo.class)
    public UserVo getCount(
            @ApiParam( required = true, name = "user", value = "入?yún)閁ser對(duì)象") @RequestBody UserVo user
    ) {
        return user;
    }

}

這樣一個(gè)簡(jiǎn)單的 SpringBoot 和Swagger-ui 結(jié)合的工程就完成了，下面啟動(dòng)運(yùn)行：

啟動(dòng)后 swagger-ui 的效果圖

github地址：Spring Boot 教程济炎、技術(shù)棧川抡、示例代碼