Swagger V2 Retrofit Generator

---

name: swagger-v2-retrofit-generator description: > Generate Android Retrofit/Kotlin client code from Swagger v2 (OpenAPI 2.0) API documentation. Supports fetching Swagger docs via HTTP with no auth, Basic Auth, Bearer Token, and API Key auth. Use when: (1) User needs to generate Retrofit Service interfaces from Swagger API, (2) User wants to create Kotlin data classes from Swagger definitions, (3) User needs to fetch Swagger v2 docs from a URL with authentication, (4) Converting Swagger API documentation to Android HTTP client code.

---

Swagger v2 Retrofit 代码生成器

从 Swagger v2 (OpenAPI 2.0) API 文档生成 Android Retrofit + Kotlin 客户端代码。

功能

从 HTTP URL 获取 Swagger v2 API 文档

支持无认证、Basic Auth、Bearer Token、API Key 认证方式

生成 Retrofit Service 接口（Kotlin）

生成数据类（Kotlin data class）

快速开始

获取 Swagger 文档

使用 scripts/fetch_swagger.py 获取 Swagger JSON：

# 无认证
python scripts/fetch_swagger.py http://api.example.com/v2/api-docs
Basic 认证
python scripts/fetch_swagger.py http://api.example.com/v2/api-docs -u admin -p admin
保存到文件
python scripts/fetch_swagger.py http://api.example.com/v2/api-docs -u admin -p admin -o swagger.json

生成 Retrofit 代码

使用 scripts/generate_retrofit.py 生成代码：

# 从文件生成
python scripts/generate_retrofit.py swagger.json -p com.dkzsxt.ruizhidian.api -o ApiService.kt
从管道生成
python scripts/fetch_swagger.py http://api.example.com/v2/api-docs -u admin -p admin | \
  python scripts/generate_retrofit.py - -p com.example.api

完整示例

# 获取并生成代码（一步完成）
python scripts/fetch_swagger.py http://api.example.com/v2/api-docs \
  -u admin -p admin | \
  python scripts/generate_retrofit.py - \
  -p com.dkzsxt.ruizhidian.api \
  -s ApiService \
  -o app/src/main/java/com/dkzsxt/ruizhidian/api/ApiService.kt

指定接口生成

查看所有可用接口

# 列出所有接口
python scripts/generate_retrofit.py swagger.json --list
搜索包含 "picture" 的接口（搜索 path/summary/description/operationId/tags）
python scripts/generate_retrofit.py swagger.json --list --search picture
只在 path 中搜索
python scripts/generate_retrofit.py swagger.json --list --search getPictureDetail --search-field path
只在 summary 中搜索
python scripts/generate_retrofit.py swagger.json --list --search "绘本详情" --search-field summary
按 tag 列出接口
python scripts/generate_retrofit.py swagger.json --list --tag "绘本接口"
列出所有 tags
python scripts/generate_retrofit.py swagger.json --list-tags

生成指定接口

# 生成单个接口: POST /picture/getPictureDetailPage
python scripts/generate_retrofit.py swagger.json \
  --path /picture/getPictureDetailPage \
  --method POST \
  -o PictureDetailApi.kt
生成多个指定接口
python scripts/generate_retrofit.py swagger.json \
  --path /picture/getPictureDetailPage \
  --path /picture/getPictureList \
  --path /user/getUserInfo \
  -o SelectedApis.kt
生成 /picture/ 路径下的所有接口
python scripts/generate_retrofit.py swagger.json \
  --path "/picture/*" \
  -o PictureApis.kt
生成所有 POST 请求
python scripts/generate_retrofit.py swagger.json \
  --method POST \
  -o PostApis.kt
只生成必要的数据类（减少代码量）
python scripts/generate_retrofit.py swagger.json \
  --path /picture/getPictureDetailPage \
  --method POST \
  --only-used-models \
  -o MinimalApi.kt

搜索生成

# 搜索 "绘本" 相关接口并生成
python scripts/generate_retrofit.py swagger.json \
  --search "绘本" \
  -o PictureApis.kt
搜索 "getPicture" 路径相关接口
python scripts/generate_retrofit.py swagger.json \
  --search "getPicture" \
  --search-field path \
  -o PictureApis.kt
搜索 summary 包含 "首页" 的接口
python scripts/generate_retrofit.py swagger.json \
  --search "首页" \
  --search-field summary \
  -o HomePageApis.kt
按 tag 生成接口
python scripts/generate_retrofit.py swagger.json \
  --tag "绘本接口" \
  -o PictureApis.kt
多个 tags
python scripts/generate_retrofit.py swagger.json \
  --tag "绘本接口" \
  --tag "用户绘本接口" \
  -o PictureUserApis.kt
组合搜索：绘本接口 + POST 方法
python scripts/generate_retrofit.py swagger.json \
  --tag "绘本接口" \
  --method POST \
  --only-used-models \
  -o PicturePostApis.kt

命令行参数

fetch_swagger.py

| 参数 | 说明 | |-----|------| | url | Swagger v2 API 文档 URL | | --auth-type | 认证方式：none / basic / bearer / api-key | | -u, --username | Basic Auth 用户名 | | -p, --password | Basic Auth 密码 | | --token | Bearer Token | | --api-key | API Key 值 | | --api-key-name | API Key 名称（默认 X-API-Key） | | --api-key-in | API Key 位置：header / query | | -o, --output | 输出文件路径（默认 stdout） |

generate_retrofit.py

| 参数 | 说明 | |-----|------| | input | 输入 JSON 文件，- 表示从 stdin 读取 | | -p, --package | 包名（默认: com.example.api） | | -s, --service-name | Service 接口名（默认: ApiService） | | --path | 指定接口路径（可多次使用，支持通配符 *） | | -m, --method | 指定 HTTP 方法（GET, POST, PUT, DELETE, PATCH） | | --search | 搜索关键词（搜索 path/summary/description/operationId/tags） | | --search-field | 指定搜索字段（可多次使用） | | --tag | 按 Tag 过滤（可多次使用） | | --only-used-models | 只生成被选中接口使用的数据类 | | -l, --list | 列出所有可用接口 | | --list-tags | 列出所有可用 Tags | | -o, --output | 输出文件路径（默认 stdout） |

生成的代码结构

生成的 Kotlin 文件包含：

package com.dkzsxt.ruizhidian.api
import retrofit2.http.*
import okhttp3.ResponseBody
// 数据类
data class User(
    val id: Long,
    val name: String
)
// Service 接口
interface ApiService {
    
    @GET("/users/{id}")
    suspend fun getUserById(
        @Path("id") id: String
    ): User
    
    @POST("/users")
    suspend fun createUser(
        @Body body: User
    ): User
}

认证方式支持

Basic Auth

使用 -u 和 -p 参数：

python scripts/fetch_swagger.py URL -u username -p password

Bearer Token (JWT)

python scripts/fetch_swagger.py URL --auth-type bearer --token TOKEN

API Key

# Header 方式
python scripts/fetch_swagger.py URL --auth-type api-key --api-key KEY --api-key-name X-API-Key
Query 方式
python scripts/fetch_swagger.py URL --auth-type api-key --api-key KEY --api-key-name token --api-key-in query

参考文档

Swagger v2 结构说明: references/swagger-v2-structure.md

Retrofit 模板: references/retrofit-templates.md

限制

仅支持 Swagger v2 (OpenAPI 2.0)，不支持 OpenAPI 3.0

生成的方法使用 suspend 函数（Kotlin 协程）

文件上传相关 API 需要手动调整

复杂泛型响应可能需要手动修改

类名处理

Swagger 中的中文类名（如 Result«绘本详情信息对象»）会自动转换为合法的 Kotlin 类名：

| 原始类名 | 生成的类名 | |---------|-----------| | Result«绘本详情信息对象» | ResultPictureBookDetailInfoObject | | 口语课商品列表对象 | OralClassGoodsListObject | | List<用户详情> | List |

转换规则： 1. 移除书名号等特殊字符 (« » 《 》 < >) 2. 常见中文词汇自动翻译（如"绘本"→"PictureBook"、"详情"→"Detail"） 3. 其他中文字符替换为 X 4. 转换为 PascalCase 格式 5. 确保以字母开头

故障排除

401 认证失败

检查用户名密码是否正确：

python scripts/fetch_swagger.py URL -u admin -p admin

无法解析 JSON

确保 URL 返回的是 Swagger v2 JSON，不是 HTML 页面。

类型映射不正确

某些复杂类型（如 Map、Any）可能需要手动调整。参考生成的代码并手动修复。

找不到指定接口

使用 --list 查看所有可用接口：

python scripts/generate_retrofit.py swagger.json --list
python scripts/generate_retrofit.py swagger.json --list --search keyword
python scripts/generate_retrofit.py swagger.json --list --search "绘本" --search-field summary

查看所有 tags：

python scripts/generate_retrofit.py swagger.json --list-tags

注意：

路径需要完全匹配或使用 * 通配符

方法名需大写（GET, POST, PUT, DELETE, PATCH）

示例：--path /picture/getPictureDetailPage --method POST

搜索支持中文，会搜索 path/summary/description/operationId/tags

生成的代码太多

使用 --only-used-models 只生成选中接口依赖的数据类：

python scripts/generate_retrofit.py swagger.json \
  --path /api/specific \
  --only-used-models \
  -o MinimalApi.kt