Swagger2學習筆記

Swagger2 學習筆記

前言

部落格書連結：點選

版本說明：

jdk=1.8.0_221
maven=3.6.1
springfox-swagger2=2.9.2

參考連結

swagger2 官方 Java 開發文檔： https://hantsy.gitbooks.io/build-a-restful-app-with-spring-mvc-and-angularjs/content/swagger.html
springfox-swagger2 maven 位址： https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
springfox-swagger-ui maven 位址： https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui

什麼是 Swagger2

編寫和維護接口文檔是每個程式員的職責，根據 Swagger2 可以快速幫助我們編寫最新的API接口文檔，再也不用擔心開會前仍忙于整理各種資料了，間接提升了團隊開發的溝通效率。常用注解swagger通過注解表明該接口會生成文檔，包括接口名、請求方法、參數、傳回資訊的等等。

核心依賴

<swagger2.version>2.9.2</swagger2.version>
<!-- SpringFox Swagger UI -->
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>${swagger2.version}</version>
 </dependency>
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>${swagger2.version}</version>
 </dependency>

Swagger2 配置類

package top.simba1949.config;
import com.google.common.base.Predicate;
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;
import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;
/**
 * 需要 @EnableSwagger2 開啟 swagger2
 * 啟動項目後通路 http://ip:port/swagger-ui.html 即可通路
 *
 * @Author Theodore
 * @Date 2019/10/23 18:34
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    /**
     * springfox.documentation.spring.web.plugins.Docket 用于建構 Springfox 架構
     * @return
     */
    @Bean
    public Docket commonDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 如果存在多個 Docket ，需要進行分組命名
                .groupName("commonDocket-api")
                // 設定 meta 資訊
                .apiInfo(apiInfo("标題：通用開發接口文檔", "描述：通用開發接口文檔"))
                // 啟動 api 選擇建構器
                .select()
                // 哪些包路徑下屬于通用開發接口文檔
                .apis(RequestHandlerSelectors.basePackage("top.simba1949.controller.common"))
                // 路徑篩選 PathSelectors.any() 比對所有接口，也可以自定義比對哪些接口
                .paths(PathSelectors.any())
                // 建構
                .build();
    }
    /**
     * 自定義比對哪些接口
     * @return
     */
    private Predicate<String> postPaths() {
        return or(
                regex("/api/posts.*"),
                regex("/api/comments.*")
        );
    }
    @Bean
    public Docket companyDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 如果存在多個 Docket ，需要進行分組命名
                .groupName("companyDocket-api")
                // 設定 meta 資訊
                .apiInfo(apiInfo("标題：公司開發接口文檔", "描述：公司開發接口文檔"))
                // 啟動 api 選擇建構器
                .select()
                // 哪些包路徑下屬于公司開發接口文檔
                .apis(RequestHandlerSelectors.basePackage("top.simba1949.controller.company"))
                // 路徑篩選
                .paths(PathSelectors.any())
                // 建構
                .build();
    }
    private ApiInfo apiInfo(String title, String description) {
        // 名稱，站點，郵箱位址
        Contact contact = new Contact("simba1949", "https://blog.csdn.net/simba1949", "[email protected]");
        return new ApiInfoBuilder()
                // 标題
                .title(title)
                // 描述
                .description(description)
                // 服務條款連結
                .termsOfServiceUrl("http://hantsy.blogspot.com")
                // 聯系人
                .contact(contact)
                // 認證許可
                .license("Apache License Version 2.0")
                // 認證許可連結
                .licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE")
                // 版本
                .version("2.0")
                .build();
    }
}

常用注解

@Api：修飾整個類，描述Controller的作用
@ApiOperation：描述一個類的一個方法，或者說一個接口
@ApiParam：單個參數描述
@ApiModel：用對象來接收參數
@ApiModelProperty：用對象接收參數時，描述對象的一個字段
@ApiIgnore：使用該注解忽略這個API，用于類或者方法上
@ApiImplicitParam：一個請求參數，用于方法上
@ApiImplicitParams：多個請求參數，包含多個 @ApiImplicitParam，用于方法上

注意

@ApiModel 和 @ApiImplicitParams 不推薦同時使用

@Api

強制：tags(數組長度建議為 1)

@Api(
        tags = {"公司管理"}, // 字元串數組；用于說明該類的作用(強制)
        authorizations = {}, // 字元串數組；用于權限配置
        consumes = "", // 字元串, 可選值："application/json, application/xml"；說明接收協定類型
        hidden = false, // 布爾類型；是否隐藏該類api
        produces = "", // 字元串，可選值："application/json, application/xml"；說明輸出協定類型
        protocols = "" // 字元串，可選值：http, https, ws, wss；說明支援的協定類型
)

@ApiOperation

強制：value

@ApiOperation(
            authorizations = {}, // 字元串數組；用于權限配置
            code = 200, // int；響應的HTTP狀态代碼。
            consumes = "", // 字元串，可選值"application/json, application/xml"，接收協定類型
            hidden = false, // 布爾類型；是否隐藏該接口
            httpMethod = "", // 字元串，可選值 "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"；接口請求方式
            notes = "操作的較長的描述。", // 字元串；操作的較長的描述。(強制)
            produces = "", // 字元串，可選值："application/json, application/xml"；說明輸出協定類型
            protocols = "", // 字元串，可選值：http, https, ws, wss；說明支援的協定類型
            response = String.class, // Class 類型；傳回類型
            responseContainer = "", // 字元串，可選值"List", "Set" or "Map"；聲明包裝響應的容器。
            responseHeaders = {}, // ResponseHeader數組；響應頭設定
            value = "接口描述或者摘要" // 字元串；接口描述或者摘要
    )

@ApiParam

強制：name、value

@ApiParam(
    name = "companyName", // 參數名
    defaultValue = "ali", // 預設值
    example = "示例", // 示例值
    value = "公司名稱", // 參數簡要說明
    hidden = false,  // 是否隐藏改參數
    required = false // 是否必須輸入
) String companyName

@ApiModel & @ApiModelProperty

@ApiModel 強制：value、description

@ApiModelProperty 強制：name、value

@ApiModel(
        value = "類名",
        description = "類的較長的描述",
        parent = Object.class // 為模型提供超類，以允許描述繼承。
)
@ApiModelProperty(
    dataType = "int", // 資料類型
    hidden = false, // 是否隐藏
    name = "id", // 屬性名稱
    required = true, // 是否必須
    value = "主鍵" // 屬性描述
)

@ApiIgnore

// 使用該注解忽略這個API，用于類或者方法上
@ApiIgnore(value = "填寫忽略該api的原因")

@ApiImplicitParam & @ApiImplicitParams

強制：@ApiImplicitParam ：name、value、dataTypeClass（dataType）

強制：@ApiImplicitParams ：value

@ApiImplicitParam ：用在請求的方法上，表示一個參數說明

@ApiImplicitParams ：用在請求的方法上，表示一組參數說明

@ApiImplicitParam(
            dataType = "int", // 字元串；入參類型
            dataTypeClass = Integer.class, // Class 類型；入參類型，如果存在會覆寫 dataType
            defaultValue = "", // 字元串；入參預設值
            name = "", // 字元串； 入參名
            required = true, // 布爾類型；是否必傳
            value = "對參數的描述", // 字元串類型；表示對參數的描述
            paramType = "" // 字元串類型，可選值path/query/body/header/form；表示參數存在位置
    )

// value 是 @ApiImplicitParam 的數組
@ApiImplicitParams(
    value = {
        @ApiImplicitParam(
            dataType = "int", // 字元串；入參類型
            name = "id", // 字元串； 入參名
            value = "公司id值", // 字元串類型；表示對參數的描述
        ),
        @ApiImplicitParam(
            dataType = "string", // 字元串；入參類型
            name = "companyName", // 字元串； 入參名
            value = "公司名稱", // 字元串類型；表示對參數的描述
        )
    }
)

Swagger2學習筆記

Swagger2 學習筆記

前言

參考連結

相關連結

什麼是 Swagger2

核心依賴

常用注解

注意

@ApiOperation

@ApiParam

@ApiModel & @ApiModelProperty

@ApiIgnore

繼續閱讀

Cloud Studio初體驗

spark/scala關于【資源檔案】加載方法概述外部檔案加載方案測試資源檔案打包入jar包中小結

NOSQL安全攻擊

mybatis_入門程式Mybatis入門

maven No compiler is provided in this environment. Perhaps you are running on a JRE rather than a J

AOP程式設計_Android優雅權限架構(1)概念基礎，2021金三銀四前言正文大綱正文

面試題解析：你接口測試是怎麼做的？

php 去掉字元串的最後一個字元及截取原字元串1,2,3,4,5,6,

Effective Java 8:通用程式設計

php——水印

OOM三種類型

工廠模式-三種類型

【遞歸】高效率求2的n次幂

win10本地scala和spark安裝安裝scala安裝spark

scala (3) Function 和 Method

Opendaylight課堂之深度剖析toaster（一）