零、前言

    接口文檔在項目開發中是非常重要的，是前後端協同開發的有力武器，如果沒有一個良好  的接口文檔來給相關開發人員查看接口的情況（或者變化），那麼前後端的開發工作耦合程度（指的是需要經常詢問接口情況）將會嚴重增加。

一、swagger簡介

    Swagger是一款Restful接口的文檔在線自動生成和功能測試功能軟件。
    
    Swagger是一個規範和完整的框架，用於生成、描述、調用和可視化Restful風格的Web服務。總體目標是使客戶端和文件系統作爲服務器以同樣的速度來更新文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。

swagger優缺點

優點

節省了大量手寫接口文檔的時間
通過註解自動生成在線文檔
接口在線調用調試

缺點

代碼耦合，需要註解支持
代碼侵入性比較強
無法測試錯誤的請求方式、參數及不限於這些

自己寫文檔的缺點

文檔更新的時候，需要再次發送一份給前端，也就是文檔更新交流不及時
接口返回結果不明確
不能直接在線測試接口，通常需要使用工具，比如postman
接口文檔太多，不好管理

二、SpringBoot 中使用swagger步驟

pom.xml

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.0</version>
</dependency>

Swagger配置類

package com.springswagger.config;

import org.springframework.beans.factory.annotation.Value;
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;

/**
 * @Description
 * @ClassName SwaggerConfig
 * @Author User
 * @date 2020.06.11 22:15
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // swagger開關，開發環境開啓，生產環境關閉
    @Value("${swagger.enabled}")
    private boolean enableSwagger;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否開啓 (true 開啓  false隱藏。生產環境建議隱藏)
                .enable(enableSwagger)
                .select()
                //掃描的路徑包,設置basePackage會將包下的所有被@Api標記類的所有方法作爲api
                .apis(RequestHandlerSelectors.basePackage("com.springswagger.controller"))
                //指定路徑處理PathSelectors.any()代表所有的路徑
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * @Description swagger基本信息
     * @Param
     * @return 
     * @Author zhen.ma
     * @Date 2020.06.11 22:26
     **/
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //設置文檔標題(API名稱)
                .title("SpringBoot使用Swagger2構建restful Api文檔")
                //文檔描述
                .description("接口說明")
                //服務條款URL
                .termsOfServiceUrl("http://127.0.0.1:8080/")
                //聯繫信息
                .contact(new Contact("san.zhang","http://san.zhang.com","[email protected]"))
                //版本號
                .version("V1.0")
                .build();
    }
}

解釋：
@Configuration標註在類上，相當於把該類作爲spring的xml配置文件中的，作用爲：配置spring容器(應用上下文)。用@Bean標註方法等價於XML中配置bean。

@EnableSwagger2的作用是啓用Swagger2相關功能。

Docket對象包含三個方面信息：

整個API的描述信息，即ApiInfo對象包括的信息，這部分信息會在頁面上展示。
指定生成API文檔的包名。
指定生成API的路徑。

controller類

只是爲了說明swagger的用法，我們只寫了controller類，如下：

package com.springswagger.controller;

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

import java.util.HashMap;
import java.util.Map;

/**
 * @Description
 * @ClassName MySwaggerController
 * @Author User
 * @date 2020.06.11 22:14
 */
@RestController
@RequestMapping("api/v1")
@Api(value = "測試接口", tags = "UserController", description = "測試接口相關")
public class MyController {

    @GetMapping("/")
    @ApiOperation(value = "訪問網站首頁", notes = "網站首頁")
    public void index() {

    }

    @GetMapping(value = "/mi", produces = "application/json")
    @ApiImplicitParam(name = "num", value = "數字", required = true, dataType = "int", paramType = "query")
    @ApiOperation(value = "一個數的平方", notes = "求一個數的平方")
    public int getNum2(@RequestParam int num) {
        return num*num;
    }
}

api文檔訪問

http://localhost:8080/swagger-ui.html

   當然，這個接口文檔非常不完善，只有一個get請求的接口說明，而且不詳細，後續將會補充完中。

    這樣，就完成了在springboot中使用swagger文檔的功能，是不是也不復雜呢，相比於nodejs中在swagger中編寫yaml文件，可以說更加直觀。

三、文檔註解說明

註解說明

常用註解說明：

@Api：用於controller類上，說明該類的作用

tags=“說明該類的作用，可以在UI界面上看到的註解”
value=“該參數沒什麼意義，在UI界面上也看到，所以不需要配置”

@ApiOperation：用在controller的方法上，用來說明方法用途、作用

value=“說明方法的用途、作用”
notes=“方法的備註說明”

@ApiImplicitParam：用來給方法入參增加說明

name：參數名
value：參數的漢字說明、解釋
dataType：參數類型，默認String
required ：參數是否必傳，true必傳
defaultValue：參數的默認值
paramType：參數放在哪個地方
header請求參數的獲取:@RequestHeader,參數從請求頭獲取
query請求參數的獲取:@RequestParam,參數從地址欄問號後面的參數獲取
path（用於restful接口）請求參數的獲取：@PathVariable，參數從URL地址上獲取
body（不常用）參數從請求體中獲取
form（不常用）參數從form表單中獲取

@ApiImplicitParams：用在controller的方法上，一組@ApiImplicitParam

@ApiResponse：用在 @ApiResponses裏邊，一般用於表達一個錯誤的響應信息

code：數字，例如400
message：信息，例如"請求參數沒填好"
response：拋出異常的類

@ApiResponses：用在controller的方法上，用於表示一組響應

@ApiModel：用在返回對象類上，描述一個Model的信息（這種一般用在post創建的時候，使用@RequestBody這樣的場景，請求參數無法使用@ApiImplicitParam註解進行描述的時候）

@ApiModelProperty：用在出入參數對象的字段上，表示對model屬性的說明或者數據操作更改

value = 字段說明
name = 重寫屬性名字
dataType = 重寫屬性類型
required = 是否必填，true必填
example = 舉例說明
hidden = 隱藏

@ApiIgnore：使用該註解忽略這個API，不會生成接口文檔。可註解在類和方法上

四、總結

   本文簡答記錄了下springboot中使用swagger生成接口文檔的基本方法，後續需要繼續完善，繼續學習實踐。

五、demo地址

   [github](https://github.com/SUST-MaZhen/spring-swagger.git)

spring boot項目利用swagger生成api文檔

零、前言

一、swagger簡介

swagger優缺點

優點

缺點

自己寫文檔的缺點

二、SpringBoot 中使用swagger步驟

pom.xml

Swagger配置類

controller類

api文檔訪問

http://localhost:8080/swagger-ui.html

三、文檔註解說明

四、總結

五、demo地址

將現有Vue項目改爲electron桌面端

Qml創建視頻通話項目（一）：Qml創建自定義登錄模塊

Web項目引入Agora SDK實現視頻通話功能

electron-vue項目搭建過程

python-opencv人眼檢測

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結