Spring Boot 入門系列（二十二）使用Swagger2構建 RESTful API文檔

前面介紹瞭如何Spring Boot 快速打造Restful API 接口，也介紹瞭如何優雅的實現 Api 版本控制，不清楚的能夠看我以前的文章：https://www.cnblogs.com/zhangweizhong/category/1657780.html

在實際項目中，Api 接口系統對接過程當中，Api 接口文檔是很是重要的文檔。通常是設計完成以後，同時編寫Api 接口文檔，而後將接口文檔發給相關人員，因而你們就按照該文檔開發、集成並最終上線。可是，這是一種很是理想的狀態，實際開發中，接口不斷變化，接口文檔也必須保持更新，這是一個很是麻煩的過程！爲了解決這些問題，Swagger2 應運而生。接下來，就和大夥聊一聊 Spring Boot 如何整合Swagger2，使用Swagger2構建 RESTful API文檔。

 

什麼是Swagger

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。是世界上最流行的 API 表達工具 。咱們知道，RESTful API 可能要面對多個開發人員或多個開發團隊：IOS開發、Android開發或是Web前端開發等。爲了減小與其餘團隊平時開發期間的頻繁溝通成本，通常咱們會建立一份API文檔來記錄全部接口細節，可是api 接口文檔存在如下問題：

• 因爲接口衆多，而且細節複雜（須要考慮不一樣的HTTP請求類型、HTTP頭部信息、HTTP請求內容等），要建立這樣一份高質量的文檔自己就是件很是吃力的事。
• 隨着需求的不斷變化，接口文檔也必須同步修改，這很容易致使文檔和業務不一致狀況出現。

爲了解決這些問題，Swagger2 應運而生。它能夠輕鬆的整合到Spring Boot 中，自動生成強大的 RESTful API文檔。這樣既能夠減小咱們建立文檔的工做量，同時說明內容又整合入實現代碼中，讓維護文檔和修改代碼整合爲一體，可讓咱們在修改代碼邏輯的同時方便的修改文檔說明。另外Swagger2也提供了完整的測試頁面，來調試每一個API 接口。

下面就以SpringBoot中集成Swagger爲例作介紹說明Swagger2 的功能和做用。

 

Spring Boot 實現Swagger 2

Spring Boot 集成 Swagger 2很簡單，首先新建一個 SpringBoot 項目，這裏就不從新建立項目，直接使用以前的rest 測試項目。而後引入依賴並作基礎配置便可：

一、配置Swagger2的依賴

在pom.xml 配置文件中，增長Swagger 2 的相關依賴，具體以下：

<!-- swagger2 依賴配置-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

注意，swagger 2 的版本號和 spring boot的版本號有些不匹配，最開始用2.2的版本和spring boot 的版本還不匹配，後來把 swagger 2 換成了2.8。

 

二、建立Swagger 2配置類

在com.weiz.config 包中，增長Swagger 2 的配置類，SwaggerConfig 類，具體代碼以下：

package com.weiz.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Config implements WebMvcConfigurer {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.weiz.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構建RESTful APIs")
                .description("Spring Boot相關文章請關注：https://www.cnblogs.com/zhangweizhong")
                .termsOfServiceUrl("https://www.cnblogs.com/zhangweizhong")
                .contact("架構師精進")
                .version("1.0")
                .build();
    }

    /**
     *  swagger增長url映射
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

說明：@Configuration 註解讓Spring boot來加載該類配置，@EnableSwagger2註解啓用Swagger 2，經過配置一個Docket Bean，配置映射路徑和要掃描的接口的位置。apiInfo，主要配置一下Swagger2文檔網站的信息，例如網站的title、網站的描述、使用的協議等等。

注意：

　　一、basePackage 能夠在SwaggerConfig 裏面配置 com.weiz.controller，也能夠在啓動器裏面 ComponentScan 配置。

　　二、須要在swaggerconfig 中配置swagger 的url 映射。

 

 三、添加文檔說明內容

上面配置完成以後，接下來須要在api 接口上增長內容說明。這裏方便起見，就直接在以前的UserController 中，增長相應的接口內容說明，代碼以下所示：

package com.weiz.controller;

import com.weiz.pojo.SysUser;
import com.weiz.service.UserService;
import com.weiz.utils.JSONResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.n3r.idworker.Sid;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@Api(tags = {"用戶接口"})
@RestController
@RequestMapping("/")
public class UserController {

    @Autowired
    private UserService userService;

    @Autowired
    private Sid sid;

    @ApiOperation(value="建立用戶", notes="根據User對象建立用戶")
    @PostMapping(value = "user")
    public JSONResult create(@RequestBody SysUser user) throws Exception {
        String userId = sid.nextShort();
        user.setId(userId);
        userService.saveUser(user);
        return JSONResult.ok("保存成功");
    }

    @ApiOperation(value="更新用戶詳細信息", notes="根據id來指定更新對象，並根據傳過來的user信息來更新用戶詳細信息")
    @PutMapping(value = "user")
    public JSONResult update(@RequestBody SysUser user) {
        userService.updateUser(user);
        return JSONResult.ok("保存成功");
    }

    @ApiOperation(value="刪除用戶", notes="根據url的id來指定刪除對象")
    @DeleteMapping("user/{userId}")
    public JSONResult delete(@PathVariable String userId) {
        userService.deleteUser(userId);
        return JSONResult.ok("刪除成功");
    }

    @ApiOperation(value="查詢用戶",notes = "經過用戶ID獲取用戶信息")
    @GetMapping("user/{userId}")
    public JSONResult queryUserById(@PathVariable String userId) {
        return JSONResult.ok(userService.queryUserById(userId));
    }
}

說明：

　　一、@Api註解，用來給整個controller 增長說明。
　　二、@ApiOperation註解，用來給各個API 方法增長說明。
　　三、@ApiImplicitParams、@ApiImplicitParam註解，用來給參數增長說明。

　　四、Swagger 還有用於對象參數的註解，對象參數的描述也能夠放在實體類中。這裏不細說，你們能夠自行研究。

 

測試驗證

完成上面的配置和代碼修改以後，Swagger 2 就集成到Spring boot 項目中了，接下來啓動Spring Boot程序，訪問：http://localhost:8088/swagger-ui.html 

 

最後

以上，就把Spring Boot 如何整合Swagger2，使用Swagger2構建 RESTful API文檔 介紹完了。實現仍是比較簡單的，可是仍是須要理解裏面的相關注解的用法。

這個系列課程的完整源碼，也會提供給你們。你們關注個人微信公衆號（架構師精進），回覆：springboot源碼。獲取這個系列課程的完整源碼。