摘要：但是這種手寫文檔帶來的弊端就是維護(hù)起來苦不堪言，對(duì)于接口容易發(fā)生變化的開發(fā)者來說，維護(hù)文檔就是噩夢好在現(xiàn)如今市場上書寫文檔的工具有很多，常見的有阿里的但是能稱之為框架的，估計(jì)也只有了。

SpringBoot 是為了簡化 Spring 應(yīng)用的創(chuàng)建、運(yùn)行、調(diào)試、部署等一系列問題而誕生的產(chǎn)物，自動(dòng)裝配的特性讓我們可以更好的關(guān)注業(yè)務(wù)本身而不是外部的XML配置，我們只需遵循規(guī)范，引入相關(guān)的依賴就可以輕易的搭建出一個(gè) WEB 工程

隨著互聯(lián)網(wǎng)技術(shù)的發(fā)展，現(xiàn)在的網(wǎng)站架構(gòu)基本都由原來的后端渲染，變成了：前端渲染、前后端分離的形態(tài)，而且前端技術(shù)和后端技術(shù)在各自的道路上越走越遠(yuǎn)。

前端和后端唯一聯(lián)系，變成了API接口；API文檔自然就成了前后端開發(fā)人員聯(lián)系的紐帶，變得尤為的重要，swagger就是一款讓你更好的書寫API文檔的框架。

沒有API文檔工具之前，基本都是手寫API文檔的，如有在Word上寫的，有在對(duì)應(yīng)的項(xiàng)目目錄下readme.md上寫的，每個(gè)公司都有每個(gè)公司的玩法，無所謂好壞。但是這種手寫文檔帶來的弊端就是維護(hù)起來苦不堪言，對(duì)于接口容易發(fā)生變化的開發(fā)者來說，維護(hù)文檔就是噩夢....

好在現(xiàn)如今市場上書寫API文檔的工具有很多，常見的有 postman、yapi、阿里的RAP 但是能稱之為框架的，估計(jì)也只有swagger了。

swagger 優(yōu)缺點(diǎn)

集成方便，功能強(qiáng)大

在線調(diào)試與文檔生成

代碼耦合，需要注解支持，但不影響程序性能

在 pom.xml 中添加 swagger-spring-boot-starter 的依賴

    org.springframework.boot
    spring-boot-starter-web


    com.battcn
    swagger-spring-boot-starter
    1.4.5-RELEASE

配置spring.swagger.enabled開啟swagger的使用，如果在生產(chǎn)環(huán)境中不想用可以在對(duì)應(yīng)的profile下面將它設(shè)置為spring.swagger.enabled=false，這樣一來接口就不存在暴露的風(fēng)險(xiǎn)

# 掃描的包路徑,默認(rèn)掃描所有
spring.swagger.base-package=com.battcn
# 默認(rèn)為 true
spring.swagger.enabled=true

swagger 提供了非常齊全的注解，為POJO提供了@ApiModel、@ApiModelProperty，以便更好的渲染最終結(jié)果

package com.battcn.entity;

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

import java.io.Serializable;

/**
 * @author Levin
 * @since 2018/5/10 0007
 */
@ApiModel
public class User implements Serializable {

    private static final long serialVersionUID = 8655851615465363473L;

    private Long id;
    @ApiModelProperty("用戶名")
    private String username;
    @ApiModelProperty("密碼")
    private String password;

    // TODO  省略get set
}

注解描述

@Api： 描述Controller

@ApiIgnore： 忽略該Controller，指不對(duì)當(dāng)前類做掃描

@ApiOperation： 描述Controller類中的method接口

@ApiParam： 單個(gè)參數(shù)描述，與@ApiImplicitParam不同的是，他是寫在參數(shù)左側(cè)的。如（@ApiParam(name = "username",value = "用戶名") String username）

@ApiModel： 描述POJO對(duì)象

@ApiProperty： 描述POJO對(duì)象中的屬性值

@ApiImplicitParam： 描述單個(gè)入?yún)⑿畔?/p>

@ApiImplicitParams： 描述多個(gè)入?yún)⑿畔?/p>

@ApiResponse： 描述單個(gè)出參信息

@ApiResponses： 描述多個(gè)出參信息

@ApiError ： 接口錯(cuò)誤所返回的信息

package com.battcn.controller;

import com.battcn.entity.User;
import com.battcn.swagger.properties.ApiDataType;
import com.battcn.swagger.properties.ApiParamType;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.*;

/**
 * swagger
 *
 * @author Levin
 * @since 2018/5/16 0016
 */
@RestController
@RequestMapping("/users")
@Api(tags = "1.1", description = "用戶管理", value = "用戶管理")
public class UserController {

    private static final Logger log = LoggerFactory.getLogger(UserController.class);

    @GetMapping
    @ApiOperation(value = "條件查詢（DONE）")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用戶名", dataType = ApiDataType.STRING, paramType = ApiParamType.QUERY),
            @ApiImplicitParam(name = "password", value = "密碼", dataType = ApiDataType.STRING, paramType = ApiParamType.QUERY),
    })
    public User query(String username, String password) {
        log.info("多個(gè)參數(shù)用  @ApiImplicitParams");
        return new User(1L, username, password);
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "主鍵查詢（DONE）")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用戶編號(hào)", dataType = ApiDataType.LONG, paramType = ApiParamType.PATH),
    })
    public User get(@PathVariable Long id) {
        log.info("單個(gè)參數(shù)用  @ApiImplicitParam");
        return new User(id, "u1", "p1");
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "刪除用戶（DONE）")
    @ApiImplicitParam(name = "id", value = "用戶編號(hào)", dataType = ApiDataType.LONG, paramType = ApiParamType.PATH)
    public void delete(@PathVariable Long id) {
        log.info("單個(gè)參數(shù)用 ApiImplicitParam");
    }

    @PostMapping
    @ApiOperation(value = "添加用戶（DONE）")
    public User post(@RequestBody User user) {
        log.info("如果是 POST PUT 這種帶 @RequestBody 的可以不用寫 @ApiImplicitParam");
        return user;
    }

    @PutMapping("/{id}")
    @ApiOperation(value = "修改用戶（DONE）")
    public void put(@PathVariable Long id, @RequestBody User user) {
        log.info("如果你不想寫 @ApiImplicitParam 那么 swagger 也會(huì)使用默認(rèn)的參數(shù)名作為描述信息 ");
    }
}

由于上面的接口是 restful 風(fēng)格的接口，添加和修改無法通過瀏覽器完成，以前都是自己編寫junit或者使用postman之類的工具。現(xiàn)在只需要打開瀏覽器輸入 http://localhost:8080/swagger-ui.html，更多操作請(qǐng)自行體驗(yàn)...

目前很多大佬都寫過關(guān)于 SpringBoot 的教程了，如有雷同，請(qǐng)多多包涵，本教程基于最新的 spring-boot-starter-parent：2.0.2.RELEASE編寫，包括新版本的特性都會(huì)一起介紹...

個(gè)人QQ：1837307557

battcn開源群（適合新手）：391619659

微信公眾號(hào)（歡迎調(diào)戲）：battcn

個(gè)人博客：http://blog.battcn.com/

全文代碼：https://github.com/battcn/spring-boot2-learning/tree/master/chapter10