Swagger 允許開發者定義 API 的路徑、請求參數、響應和其他相關信息，以便生成可讀性較高的文檔和自動生成客戶端代碼。而 Array （數組）是一種常見的數據結構，用于存儲和組織多個相同類型的數據元素。數組可以有不同的維度和大小，通過索引訪問特定位置的元素。

Swagger 中對 Array 類型的支持允許開發者明確定義和描述 API 中涉及的數組類型參數和響應。通過指定數組元素的類型、約束和格式，開發者可以清晰地描述 API 的使用方式和預期輸出。

Swagger Array 用法介紹

在 Swagger 中，你可以使用 OpenAPI 規范 來描述和定義 API，包括數組類型參數和響應的規范。下面是一些常見的 Swagger Array 的用法介紹：

定義數組參數

在 Swagger 中，你可以使用 "in" 屬性將數組參數聲明為路徑參數、查詢參數、請求體參數或響應參數。例如，如果你想定義一個名為 "ids" 的路徑參數，它接受一個整數數組作為值，你可以使用以下示例：

paths:/example/{ids}:get:parameters:- in: pathname: idsrequired: trueschema:type: arrayitems:type: integer

在上述示例中，"schema" 屬性表示參數的類型為數組，其中 "items" 屬性指定了數組元素的類型為整數。

定義數組響應

類似于定義數組參數，你也可以在 Swagger 中定義 API 的響應為數組。在 OpenAPI 規范中，你可以使用 "schema" 屬性來指定響應的數據結構。以下示例說明了如何定義一個返回用戶列表（數組）的 API 響應：

paths:/users:get:responses:'200':description: OKcontent:application/json:schema:type: arrayitems:type: objectproperties:name:type: string

在上述示例中，"schema" 屬性指示響應的數據類型為數組，其中 "items" 屬性定義了數組元素的類型為一個對象，并指定了該對象包含一個名為 "name" 的字符串屬性。

使用數組參數或響應

在 Swagger 的請求示例和響應示例中，你可以使用具體的數組值來演示 API 的使用。例如，在請求示例中，你可以為數組參數提供一組整數值。在響應示例中，你可以提供一組對象數組作為 API 返回的示例數據。這些是 Swagger 中數組的常見用法。使用 Swagger，你可以清楚明確地定義和描述 API 的數組類型參數和響應，方便開發者理解和使用你的 API。

在 SpringBoot 項目中配置

在 Spring Boot 項目中使用 Swagger 來配置數組類型參數和響應的規范，你可以遵循以下步驟：

1. 添加 Swagger 依賴：在 Maven 或 Gradle 配置文件中添加 Swagger 的依賴項，以便在你的 Spring Boot 項目中使用 Swagger。Maven 的示例配置如下：

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>

1. 創建 Swagger 配置類：創建一個 Swagger 配置類，用于配置 Swagger 的相關信息和規范。創建一個類，并使用@Configuration注解標記它：

@Configuration
public class SwaggerConfig {// Swagger 配置內容
}

1. 配置 Swagger Docket：在 Swagger 配置類中，創建一個Docket Bean，并進行必要的配置，如 API 文檔的標題、描述等。還可以使用select()方法來選擇要包含在文檔中的 API 接口。下面是一個示例配置：

@Bean
public Docket api() {return new Docket(DocumentationType.SWAGGER_2).groupName("API").select().apis(RequestHandlerSelectors.basePackage("com.example")).paths(PathSelectors.any()).build().apiInfo(apiInfo());
}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("API Documentation").description("API Documentation for my Spring Boot project").version("1.0").build();
}

1. 配置數組參數或響應：在使用 Swagger 的注解時，你可以使用數組類型來表示參數或響應。例如，在使用 @ApiOperation 注解的方法上，可以使用@ApiParam注解來說明數組類型的參數。在使用 @ApiResponse 注解的方法上，可以使用content屬性指定數組類型的響應。下面是一些示例：

@ApiOperation("Get user by IDs")
@GetMapping("/users/{ids}")
public ResponseEntity<List<User>> getUsersByIds(@ApiParam(value = "User IDs", allowMultiple = true) @PathVariable List<Long> ids) {// API 方法實現
}@ApiOperation("Get users")
@GetMapping("/users")
public ResponseEntity<List<User>> getUsers() {// API 方法實現
}

1. 運行和訪問 Swagger 文檔：在完成以上配置后，你可以啟動 Spring Boot 應用程序，并訪問 Swagger 文檔的 URL（默認為http://localhost:8080/swagger-ui/index.html），然后你將能夠查看和測試文檔中包含的數組類型參數和響應。

Swagger Array 使用注意事項

在使用 Swagger Array 時，你需要注意以下事項：

1. 數據類型和格式：確保正確指定數組元素的數據類型和格式。在 Swagger 中，可以使用type指定基本數據類型，也可以使用$ref指定引用類型。確保數組中的所有元素類型與聲明的類型一致。
2. 參數說明：對于數組類型的參數，使用@ApiParam注解來提供參數的詳細說明。可以使用value屬性來描述參數的用途和含義，使用allowMultiple屬性指定是否允許傳遞多個值。
3. 字段說明：對于數組類型的響應，可以使用@ApiModelProperty注解或者@Schema注解來提供字段的詳細說明和描述。這樣可以使開發者更好地理解和使用響應中的數組類型數據。
4. 可選性和必需性：使用 Swagger 注解來指示數組類型參數或響應是可選的還是必需的，以及它們的默認值。使用required屬性來指定是否為必需參數。
5. 示例數據：為了更好地演示和理解數組類型的參數和響應，可以使用 Swagger 的注解提供示例數據。使用example屬性來指定示例值，或使用@Example注解提供更詳細的示例數據。

Swagger 和 Apifox 整合

Swagger 管理接口有時很不方便，缺乏一定的安全性和團隊間的分享協作，你可以試試 Apifox 的 IDEA 插件。你可以在 IDEA 中自動同步 Swagger 注解到 Apifox，一鍵生成接口文檔，多端同步，非常方便測試和維護，這樣就可以迅速分享 API 給其他小伙伴。

Apifox = Postman + Swagger + Mock + JMeter，Apifox 支持調試 http（s）、WebSocket、Socket、gRPC、Dubbo 等協議的接口，并且集成了 IDEA 插件。

Apifox 的 IDEA 插件可以自動解析代碼注釋，并基于 Javadoc、KDoc 和 ScalaDoc 生成 API 文檔。通過 IntelliJ IDEA 的 Apifox Helper 插件，開發人員可以在不切換工具的情況下將他們的文檔與 Apifox 項目同步。

當在 IDEA 項目中有接口信息變動，只需右鍵點擊「 Upload to Apifox」一鍵即可完成同步，無需奔走相告。 團隊成員可在 Apifox 中看到同步后的最新內容。

知識擴展：

• Swagger basepath 用法及常見問題詳解
• Swagger Basic Authentication（身份驗證）配置

參考鏈接

• Swagger 官方文檔：Swagger Documentation
• Springfox 官方文檔：Springfox Reference Documentation