一塊兒來學SpringBoot | 第十一篇：集成Swagger在線調試

時間 2019-12-08

標籤一塊兒 springboot 第十一篇集成 swagger 在線調試欄目 Spring 简体版

原文原文鏈接

SpringBoot 是爲了簡化 Spring 應用的建立、運行、調試、部署等一系列問題而誕生的產物， 自動裝配的特性讓咱們能夠更好的關注業務自己而不是外部的XML配置，咱們只需遵循規範，引入相關的依賴就能夠輕易的搭建出一個 WEB 工程

隨着互聯網技術的發展，如今的網站架構基本都由原來的後端渲染，變成了：前端渲染、先後端分離的形態，並且前端技術和後端技術在各自的道路上越走越遠。 html

前端和後端惟一聯繫，變成了API接口；API文檔天然就成了先後端開發人員聯繫的紐帶，變得尤其的重要，swagger就是一款讓你更好的書寫API文檔的框架。前端

java

文檔工具

沒有API文檔工具以前，基本都是手寫API文檔的，若有在Word上寫的，有在對應的項目目錄下readme.md上寫的，每一個公司都有每一個公司的玩法，無所謂好壞。可是這種手寫文檔帶來的弊端就是維護起來苦不堪言，對於接口容易發生變化的開發者來講，維護文檔就是噩夢....git

好在現現在市場上書寫API文檔的工具備不少，常見的有 postman、yapi、阿里的RAP 可是能稱之爲框架的，估計也只有swagger了。github

swagger 優缺點

集成方便，功能強大
在線調試與文檔生成
代碼耦合，須要註解支持，但不影響程序性能

導入依賴

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

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>com.battcn</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.4.5-RELEASE</version>
</dependency>

屬性配置

配置spring.swagger.enabled開啓swagger的使用，若是在生產環境中不想用能夠在對應的profile下面將它設置爲spring.swagger.enabled=false，這樣一來接口就不存在暴露的風險spring

# 掃描的包路徑,默認掃描全部
spring.swagger.base-package=com.battcn
# 默認爲 true
spring.swagger.enabled=true

實體類

swagger 提供了很是齊全的註解，爲POJO提供了@ApiModel、@ApiModelProperty，以便更好的渲染最終結果後端

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
}

restful 風格接口

註解描述

@Api： 描述Controller
@ApiIgnore： 忽略該Controller，指不對當前類作掃描
@ApiOperation： 描述Controller類中的method接口
@ApiParam： 單個參數描述，與@ApiImplicitParam不一樣的是，他是寫在參數左側的。如（@ApiParam(name = "username",value = "用戶名") String username）
@ApiModel： 描述POJO對象
@ApiProperty： 描述POJO對象中的屬性值
@ApiImplicitParam： 描述單個入參信息
@ApiImplicitParams： 描述多個入參信息
@ApiResponse： 描述單個出參信息
@ApiResponses： 描述多個出參信息
@ApiError ： 接口錯誤所返回的信息

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("多個參數用  @ApiImplicitParams");
        return new User(1L, username, password);
    }

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

    @DeleteMapping("/{id}")
    @ApiOperation(value = "刪除用戶（DONE）")
    @ApiImplicitParam(name = "id", value = "用戶編號", dataType = ApiDataType.LONG, paramType = ApiParamType.PATH)
    public void delete(@PathVariable Long id) {
        log.info("單個參數用 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 也會使用默認的參數名做爲描述信息 ");
    }
}