@apiparam參數詳解

一、@apiparam參數說明

@apiparam是Swagger中用來描述API操作的參數對象的關鍵字，它是Swagger參數中的一種。它的作用是：定義HTTP請求時所使用的參數，以及在API操作中所使用的輸入參數和輸出參數

我們經常在編寫API接口文檔時會用到@apiparam關鍵字，一般來說，使用@apiparam可以提供很多對API的參數操作描述信息，例如參數名稱、參數位置、參數類型等等。

在Swagger中，定義一個參數時，需要使用@apiparam關鍵字。如下所示：

/**
 * 獲取用戶信息
 * 
 * @param {string} userId 用戶ID
 * @param {string} token 用戶Token
 * @param {string} [gender] 性別
 * @return {Object} 用戶信息
 */

在上面的代碼中，@apiparam關鍵字的使用非常簡單，它後面的內容描述了在獲取用戶信息API操作中用到的參數以及參數的類型和說明。其中，參數名稱是必填項，其他參數則可選。我們來詳細看一下每個參數的含義。

二、apidmini6參數

apidmini6是Swagger中一些常用的參數選項，在@apiparam中也可以用來進行參數定義

1、in參數

in參數是指參數的位置，有以下幾種選擇：

• path：參數位於URL路徑中
• query：參數位於查詢參數中
• header：參數位於請求頭信息中
• cookie：參數位於cookie中

例如：

/**
 * @param {number} petId 在URL路徑中的寵物ID
 */

2、required參數

required參數指定參數是否可以為空。它的值可以是true或者false。

/**
 * @param {number} petId 在URL路徑中的寵物ID
 * @param {string} [status] 寵物狀態，默認為"available"
 */

上述代碼中，petId參數是必須的，而status不是必須的，因為status的required參數值為false。

3、description參數

description參數用於描述參數的含義。

/**
 * @param {number} petId 在URL路徑中的寵物ID
 * @param {string} [status] 寵物狀態，默認為"available"
 * @param {string} [name] 寵物名字
 * @param {string} [tag] 寵物標籤
 */

上述代碼中，每個參數都使用了description參數進行了參數描述。

4、example參數

example參數用於提供值的示例，以便用戶了解如何填寫參數值。

/**
 * @param {number} petId 在URL路徑中的寵物ID。例如：54321
 * @param {string} [status] 寵物狀態，默認為"available"。例如："sold"
 * @param {string} [name] 寵物名字。例如："狗狗"
 * @param {string} [tag] 寵物標籤。例如："藍色"
 */

上述代碼中，每個參數都使用了example參數提供了示例值，使用戶能夠更好的了解如何填寫參數值。

5、format參數

format參數通過提供數據的格式，來提供有關傳遞數據的附加信息。

/**
 * @param {string} username 用戶名
 * @param {string} password 密碼
 */

在上述代碼中，格式是沒有說明的。例如，我們可以將格式指定為”password”：

/**
 * @param {string} username 用戶名
 * @param {string} password 密碼
 *     @format password
 */

三、其他參數

除了apidmini6參數選項之外，Swagger還有其他一些常見的參數選項，可以在@apiparam中使用。

1、type參數

type參數指定參數的類型。它的類型可以是字符串、數字、整數、布爾值、數組等。

/**
 * @param {string} username 用戶名
 * @param {string} password 密碼
 * @param {number} age 年齡
 * @param {boolean} isVip 是否是VIP用戶
 * @param {array} tags 標籤
 */

2、minimum和maximum參數

minimum和maximum參數用於指定參數的最小值和最大值。

/**
 * @param {number} age 年齡
 *     @minimum 18
 *     @maximum 100
 */

在上述代碼中，用戶的age參數的值必須在18到100之間。

3、pattern參數

pattern參數通過正則表達式匹配值。例如，下面例子中，email參數必須是有效的電子郵件地址：

/**
 * @param {string} email 電子郵件地址
 *     @pattern ^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$
 */

4、enum參數

enum參數用於指定參數值的範圍。例如：

/**
 * @param {string} status 訂單狀態
 *     @enum {string} placed - 訂單已經下單
 *           {string} approved - 訂單已經批准
 *           {string} delivered - 訂單已經交付
 */

在上述代碼中，status參數的值只能為三種枚舉類型之一，包括placed、approved和delivered。

5、items參數

items參數用於指定數組或對象類型的元素的類型。例如，在下面的代碼中，pets參數是一個包含pet對象的數組：

/**
 * @param {array} pets 包含pet對象的數組
 *     @items {object} pet
 *           {string} name 名稱
 *           {string} species 種類
 */

在上述代碼中，description參數中的items用來指定數組中元素的類型。

總結

本文介紹了@apiparam關鍵字以及與之相關的apidmini6參數選項和其他參數選項，每個參數選項都有詳細的闡述和示例，希望本文對大家編寫Swagger文檔有所幫助。