SpringBoot 實戰 (五) | 集成 Swagger2 構建強大的 RESTful API

Rindia 發布于2019-08-16 15:12 / 2507人閱讀

摘要：今天給你們帶來集成的教程。接口返回結果不明確。這些痛點在前后端分離的大型項目上顯得尤為煩躁。接口返回結果非常明確，包括數據類型，狀態碼，錯誤信息等。生成后的文件依賴如下這里使用的是的版本。另外，關注之后在發送可領取免費學習資料。

微信公眾號：一個優秀的廢人
如有問題或建議，請后臺留言，我會盡力解決你的問題。

前言

快過年了，不知道你們啥時候放年假，忙不忙。反正我是挺閑的，所以有時間寫 blog。今天給你們帶來 SpringBoot 集成 Swagger2 的教程。

什么是 Swagger2

Swagger 是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。

為什么使用 Swagger2 ？

相信剛開始不熟悉 web 開發的時候，大家都有手寫 Api 文檔的時候。而手寫 Api 文檔主要有以下幾個痛點：

文檔需要更新的時候，需要再次發送一份給前端，也就是文檔更新交流不及時。

接口返回結果不明確。

不能直接在線測試接口，通常需要使用工具，比如 postman。

接口文檔太多，不好管理。

這些痛點在前后端分離的大型項目上顯得尤為煩躁。而 Swagger2 的出現恰好能個解決這些痛點。因為 Swagger2 有以下功能：

文檔自動更新，只要生成 Api 的網址沒變，基本不需要跟前端溝通。

接口返回結果非常明確，包括數據類型，狀態碼，錯誤信息等。

可以直接在線測試文檔，而且還有實例提供給你。

只需要一次配置便可使用，之后只要會有一份接口文檔，非常易于管理。

集成演示

首先新建一個 SpringBoot 項目，還不會的參考我這篇舊文—— 如何使用 IDEA 構建 Spring Boot 工程

構建時，在選擇依賴那一步勾選 Web、LomBok、JPA 和 Mysql 依賴。其中 Mysql 可以不勾，因為我這里用于操作實際的數據庫，所以我勾選了。

生成 SpringBoot 后的 Pom 文件依賴如下：這里使用的是 2.4.0 的 Swagger2 版本。



    4.0.0
    
        org.springframework.boot
        spring-boot-starter-parent
        2.1.2.RELEASE
         
    
    com.nasus
    swagger2
    0.0.1-SNAPSHOT
    swagger2
    Demo project for Swagger2

    
        1.8
    

    
        
            org.springframework.boot
            spring-boot-starter-data-jpa
        

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

        
            mysql
            mysql-connector-java
            runtime
        

        
            org.springframework.boot
            spring-boot-starter-test
            test
        

        
            io.springfox
            springfox-swagger2
            2.4.0
        

        
            io.springfox
            springfox-swagger-ui
            2.4.0
        
    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin

第二步，在 SpringBoot 啟動類（Application）的同級目錄新建一個 Swagger 配置類，注意 Swagger2 配置類必須與項目入口類 Application 位于同一級目錄，否則生成 Api 文檔失敗，代碼如下：

package com.nasus;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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;

/**
 * Project Name:swagger2-demo 

 * Package Name:com.nasus 

 * Date:2019/1/22 22:52 

 * Description: TODO: 描述該類的作用 

 *
 * @author nasus

 * Copyright Notice =========================================================
 * This file contains proprietary information of Eastcom Technologies Co. Ltd.
 * Copying or reproduction without prior written approval is prohibited.
 * Copyright (c) 2019 =======================================================
 */
@Configuration
// 啟用 Swagger2
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 文檔信息對象
                .apiInfo(apiInfo())
                .select()
                // 被注解的包路徑
                .apis(RequestHandlerSelectors.basePackage("com.nasus.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 標題
                .title("springboot 利用 swagger 構建 API 文檔")
                // Api 文檔描述
                .description("簡單優雅的 restful 風格，https://blog.csdn.net/turodog/")

                .termsOfServiceUrl("https://blog.csdn.net/turodog/")
                // 文檔作者信息
                .contact(new Contact("陳志遠", "https://github.com/turoDog", "turodog@foxmail.com"))
                // 文檔版本
                .version("1.0")
                .build();
    }
}

第三步，配置被注解的 Controller 類，編寫各個接口的請求參數，返回結果，接口描述等等，代碼如下：

package com.nasus.controller;

import com.nasus.entity.Student;
import com.nasus.service.StudentService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

/**
 * Project Name:swagger2-demo 

 * Package Name:com.nasus.controller 

 * Date:2019/1/22 22:07 

 * Description: TODO: 描述該類的作用 

 *
 * @author nasus

 * Copyright Notice =========================================================
 * This file contains proprietary information of Eastcom Technologies Co. Ltd.
 * Copying or reproduction without prior written approval is prohibited.
 * Copyright (c) 2019 =======================================================
 */
@RestController
@RequestMapping("/student")
// @Api：修飾整個類，描述Controller的作用
@Api("StudentController Api 接口文檔")
public class StudentController {

    @Autowired
    private StudentService studentService;

    // @ApiOperation：描述一個類的一個方法，或者說一個接口
    @ApiOperation(value="獲取所有學生列表", notes="獲取所有學生列表")
    @RequestMapping(value={""}, method= RequestMethod.GET)
    public List getStudent() {
        List list = studentService.findAll();
        return list;
    }

    @ApiOperation(value="添加學生信息", notes="添加學生信息")
    // @ApiImplicitParam：一個請求參數
    @ApiImplicitParam(name = "student", value = "學生信息詳細實體", required = true, dataType = "Student")
    @PostMapping("/save")
    public Student save(@RequestBody Student student){
        return studentService.save(student);
    }

    @ApiOperation(value="獲學生信息", notes="根據url的id來獲取學生詳細信息")
    @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Integer",paramType = "path")
    @GetMapping("/{id}")
    public Student findById(@PathVariable("id") Integer id){
        return studentService.findById(id);
    }

    @ApiOperation(value="刪除學生", notes="根據url的id來指定刪除的學生")
    @ApiImplicitParam(name = "id", value = "學生ID", required = true, dataType = "Integer",paramType = "path")
    @DeleteMapping("/{id}")
    public String deleteById(@PathVariable("id") Integer id){
        studentService.delete(id);
        return "success";
    }

    @ApiOperation(value="更新學生信息", notes="根據url的id來指定更新學生信息")
    // @ApiImplicitParams：多個請求參數
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "學生ID", required = true, dataType = "Integer",paramType = "path"),
            @ApiImplicitParam(name = "student", value = "學生實體student", required = true, dataType = "Student")
    })
    @PutMapping(value="/{id}")
    public String updateStudent(@PathVariable Integer id, @RequestBody Student student) {
        Student oldStudent = this.findById(id);
        oldStudent.setId(student.getId());
        oldStudent.setName(student.getName());
        oldStudent.setAge(student.getAge());
        studentService.save(oldStudent);
        return "success";
    }

    // 使用該注解忽略這個API
    @ApiIgnore
    @RequestMapping(value = "/hi", method = RequestMethod.GET)
    public String  jsonTest() {
        return " hi you!";
    }
}

第四步，啟動項目，訪問 http://localhost:8080/swagger-ui.html 地址，結果如下圖：

項目源代碼

github

圖解接口

Swagger2 常用注解簡介

@ApiOperation：用在方法上，說明方法的作用
  1.value: 表示接口名稱
  2.notes: 表示接口詳細描述 
@ApiImplicitParams：用在方法上包含一組參數說明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數的各個方面
  1.paramType：參數位置
  2.header 對應注解：@RequestHeader
  3.query 對應注解：@RequestParam
  4.path  對應注解: @PathVariable
  5.body 對應注解: @RequestBody
  6.name：參數名
  7.dataType：參數類型
  8.required：參數是否必須傳
  9.value：參數的描述
  10.defaultValue：參數的默認值
@ApiResponses：用于表示一組響應
@ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應信息
  1.code：狀態碼
  2.message：返回自定義信息
  3.response：拋出異常的類
@ApiIgnore: 表示該接口函數不對swagger2開放展示
@Api：修飾整個類，描述Controller的作用
@ApiParam：單個參數描述
@ApiModel：用對象來接收參數
@ApiProperty：用對象接收參數時，描述對象的一個字段
@ApiIgnore：使用該注解忽略這個API
@ApiError ：發生錯誤返回的信息

注意事項

@ApiImplicitParam 注解下的 paramType 屬性,會影響接口的測試,如果設置的屬性跟spring 的注解對應不上,會獲取不到參數,例如 paramType=path ,函數內卻使用@RequestParam 注解,這樣,可能會獲取不到傳遞進來的參數,需要按照上面進行對應,將 @RequestParam 注解改為 @PathVariable 才能獲取到對應的參數。

后語

以上就是我對 Swagger2 的理解與使用，以上只是教大家入門 Swagger2 ，想要深入使用還是希望自行查閱官方文檔。最后，對 Python 、Java 感興趣請長按二維碼關注一波，我會努力帶給你們價值，如果覺得本文對你哪怕有一丁點幫助，請幫忙點好看，讓更多人知道。

另外，關注之后在發送 1024 可領取免費學習資料。資料內容詳情請看這篇舊文：Python、C++、Java、Linux、Go、前端、算法資料分享

GPU云服務器云服務器 restful_api返回 php 集成構建高性能linux服務器構建實戰強大的js

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/73335.html

SpringBoot非官方教程 | 第十一篇：SpringBoot集成swagger2，構建優雅的R

摘要：另外很容易構建風格的，簡單優雅帥氣，正如它的名字。配置一些基本的信息。三寫生產文檔的注解通過注解表明該接口會生成文檔，包括接口名請求方法參數返回信息的等等。四參考資料中使用構建強大的文檔 swagger,中文拽的意思。它是一個功能強大的api框架，它的集成非常簡單，不僅提供了在線文檔的查閱，而且還提供了在線文檔的測試。另外swagger很容易構建restful風格的api，簡單優雅帥氣...

荊兆峰 2019-08-16 10:44 評論0 收藏0
SpringBoot 2.X Kotlin與Swagger2生成API文檔

摘要：再通過函數創建的之后，用來創建該的基本信息這些基本信息會展現在文檔頁面中。函數返回一個實例用來控制哪些接口暴露給來展現，本例采用指定掃描的包路徑來定義，會掃描該包下所有定義的，并產生文檔內容除了被指定的請求。 showImg(http://download.qfeoo.com/kotlin_springboot_logo.png); 這里有個地方需要注意，在測試WebFlux集成Swa...

cyqian 2019-08-16 16:38 評論0 收藏0
《 Kotlin + Spring Boot ：下一代 Java 服務端開發》

摘要：下一代服務端開發下一代服務端開發第部門快速開始第章快速開始環境準備，，快速上手實現一個第章企業級服務開發從到語言的缺點發展歷程的缺點為什么是產生的背景解決了哪些問題為什么是的發展歷程容器的配置地獄是什么從到下一代企業級服務開發在移動開發領域《 Kotlin + Spring Boot ：下一代 Java 服務端開發》 Kotlin + Spring Boot ：下一代 Java...

springDevBird 2019-08-15 12:30 評論0 收藏0