天天看點
傳回

SpringBoot從入門到精通（二十二）使用Swagger2優雅建構 RESTful API文檔

前面介紹了如何Spring Boot 快速打造Restful API 接口，也介紹了如何優雅的實作 Api 版本控制。

在實際項目中，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 測試項目。然後引入依賴并做基礎配置即可：

1、配置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。

2、建立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、網站的描述、使用的協定等等。

注意：

　　1、basePackage 可以在SwaggerConfig 裡面配置 com.weiz.controller，也可以在啟動器裡面 ComponentScan 配置。

　　2、需要在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));
    }
}

說明：

　　1、@Api注解，用來給整個controller 增加說明。

　　2、@ApiOperation注解，用來給各個API 方法增加說明。

　　3、@ApiImplicitParams、@ApiImplicitParam注解，用來給參數增加說明。

　　4、Swagger 還有用于對象參數的注解，對象參數的描述也可以放在實體類中。這裡不細說，大家可以自行研究。

四、測試驗證

完成上面的配置和代碼修改之後，Swagger 2 就內建到Spring boot 項目中了，接下來啟動Spring Boot程式，通路：

http://localhost:8088/swagger-ui.html
SpringBoot從入門到精通（二十二）使用Swagger2優雅建構 RESTful API文檔

最後

以上，就把Spring Boot 如何整合Swagger2，使用Swagger2建構 RESTful API文檔 介紹完了。實作還是比較簡單的，但是還是需要了解裡面的相關注解的用法。

這個系列課程的完整源碼，也會提供給大家。大家關注我的微信公衆号（架構師精進），回複：springboot源碼。擷取這個系列課程的完整源碼。

推薦閱讀：

SpringBoot從入門到精通（二十一）如何優雅的設計 RESTful API 接口版本号，實作 API 版本控制！ SpringBoot從入門到精通（二十）快速建構RESTful Web API 服務 SpringBoot從入門到精通（十九）使用注解實作動态Sql、參數傳遞 SpringBoot從入門到精通（十八）Mybatis系列之——使用注解的方式實作背景管理功能 SpringBoot從入門到精通（十七）MyBatis系列之——建立自定義mapper 實作多表關聯查詢！ SpringBoot從小白到精通（十六）使用pagehelper實作分頁查詢功能 SpringBoot從小白到精通（十五）實作開發環境熱部署 SpringBoot從小白到精通（十四）使用JdbcTemplate操作資料庫，配置多資料源！ SpringBoot從小白到精通（十三）如何實作事務儲存 SpringBoot從小白到精通（十二）logback日志配置 SpringBoot從小白到精通（十一）統一異常處理 SpringBoot從小白到精通（十）使用Interceptor攔截器，一學就會！ SpringBoot從小白到精通（九）使用@Async實作異步執行任務 SpringBoot從小白到精通（八）熟悉@EnableScheduling，一秒搞定定時任務 SpringBoot從小白到精通（七）使用Redis實作高速緩存架構 SpringBoot從小白到精通（六）使用Mybatis實作增删改查【附詳細步驟】 SpringBoot從小白到精通（五）Thymeleaf的文法及常用标簽 SpringBoot從小白到精通（四）Thymeleaf頁面模闆引擎 SpringBoot從小白到精通（三）系統配置及自定義配置 SpringBoot從小白到精通（二）如何傳回統一的資料格式 SpringBoot從小白到精通（一）如何快速建立SpringBoot項目
架構師 NoSQL java 資料庫連接配接 api Redis android開發 網絡架構 spring mybatis restful使用api文檔 swagger restful文檔生成 restful建構web swagger restful接口 restful api文檔
上一篇: 阿裡雲ECS使用體驗
下一篇: 使用ESC學習Linux等體驗| 在Linux中叫做管道符 A|B

繼續閱讀