Swagger/OpenAPI 在 Kotlin 中的代码生成：工具与示例

Swagger/OpenAPI 为 Kotlin 生成代码：从规范到成品代码

现代 API 的开发需要清晰的文档和快速的客户端及服务端代码生成。Swagger/OpenAPI 是描述 RESTful 接口的标准，它能够自动生成 Kotlin 代码，使开发者免于手动编写 DTO、控制器和客户端的繁琐工作。本文将介绍主要工具、配置示例以及实际使用场景。

什么是 OpenAPI，为什么 Kotlin 开发者需要它？

OpenAPI（原 Swagger）是一种 YAML 或 JSON 格式的规范，用于描述端点、数据模型、请求和响应参数。对于 Kotlin，从 OpenAPI 生成代码可以带来：

• 自动化——生成 data 类、枚举、控制器接口
• 一致性——代码始终与文档保持一致
• 节省时间——无需手动编写序列化/反序列化代码
• 框架支持——Ktor、Spring Boot、Retrofit、Micronaut

主要代码生成工具

Kotlin 有几种成熟的解决方案：

1. OpenAPI Generator（官方生成器）

最流行的工具。支持数十种语言和框架。针对 Kotlin 可用的生成器有：

• kotlin-client——基于 Ktor 或 Retrofit 的客户端
• kotlin-server——基于 Ktor 或 Spring 的服务端
• kotlin-spring——Spring Boot 控制器

2. Ktor OpenAPI 插件

用于 Ktor 框架的插件，可从代码生成 OpenAPI 文档（逆向方法）。

3. Swagger Codegen（旧版）

OpenAPI Generator 的前身，仍在使用，但建议迁移到新版本。

示例：从 OpenAPI 规范生成 Kotlin 客户端

让我们看一个实际示例。假设我们有一个 petstore.yaml 文件（标准的 Petstore 规范）。我们将使用 OpenAPI Generator 生成 Kotlin 客户端。

步骤 1. 安装 OpenAPI Generator

通过 Homebrew（macOS/Linux）：

brew install openapi-generator

或通过 Docker：

docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate \  -i /local/petstore.yaml \  -g kotlin-client \  -o /local/out/kotlin-client

步骤 2. 配置生成

创建一个配置文件 config.json：

{  "packageName": "com.pythonlib.petstore.client",  "library": "ktor",  "serializationLibrary": "kotlinx_serialization",  "useCoroutines": true}

步骤 3. 运行生成

openapi-generator generate \  -i petstore.yaml \  -g kotlin-client \  -o ./generated-client \  -c config.json

结果：生成的代码

在 generated-client 文件夹中会出现：

• src/main/kotlin/com/pythonlib/petstore/client/models/Pet.kt
• src/main/kotlin/com/pythonlib/petstore/client/api/PetApi.kt

生成的 DTO 示例：

@Serializabledata class Pet(    val id: Long? = null,    @SerialName("category")    val category: Category? = null,    @SerialName("name")    val name: String,    @SerialName("photoUrls")    val photoUrls: List<String>,    val tags: List<Tag>? = null,    val status: PetStatus? = null)

@Serializableenum class PetStatus {    @SerialName("available")    Available,    @SerialName("pending")    Pending,    @SerialName("sold")    Sold}

生成的 API 客户端示例（Ktor）：

class PetApi(private val client: HttpClient) {

    suspend fun addPet(pet: Pet): Pet = cli