Swagger Codegen

这是 Swagger Codegen 项目，它允许在给定 OpenAPI 描述的情况下自动生成 API 客户端库（SDK 生成）、服务器存根和文档。

💚 如果您想贡献，请参阅指南以及待处理任务列表。💚

📔 欲了解更多信息，请参阅Wiki 页面和常见问题解答。📔

⚠️ 如果 OpenAPI 描述或 Swagger 文件来自不受信任的来源，请在使用 Swagger Codegen 生成 API 客户端、服务器存根或文档之前仔细检查该工件，因为可能会发生代码注入。⚠️

版本控制

⚠️ 本文档指 3.X 版本，2.X 版本请查看此处。

Swagger Codegen 的 2.X 和 3.X 版本均可用，并独立维护。

注意

版本 2.X (io.swagger) 和 3.X (io.swagger.codegen.v3) 具有不同的组 ID。
OpenAPI 3.0.X 仅支持 3.X 版本

有关完整的版本信息，请参阅版本控制文档。

支持的语言和框架

以下是支持的语言/框架的摘要。

API 客户端：“csharp”、“csharp-dotnet2”、“dart”、“go”、“java”、“javascript”、“jaxrs-cxf-client”、“kotlin-client”、“php”、“python”、“r”、“ruby” “scala”、“swift3”、“swift4”、“swift5”、“typescript-angular”、“typescript-axios”、“typescript-fetch”
服务器存根：“aspnetcore”、“go-server”、“inflector”、“java-vertx”、“jaxrs-cxf”、“jaxrs-cxf-cdi”、“jaxrs-di”、“jaxrs-jersey”、“jaxrs-resteasy”、“jaxrs-resteasy-eap”、“jaxrs-spec”、“kotlin-server”、“micronaut”、“nodejs-server”、“python-flask”、“scala-akka-http-server”、“spring”
API 文档生成器：“dynamic-html”、“html”、“html2”、“openapi”、“openapi-yaml”

要获取支持的语言/框架的完整和/或实时列表，您可以直接查询在线生成器 API 或通过 cURL 命令。

1
curl -X 'GET' \
2
  'https://generator3.swagger.io/api/client/V3' \
3
  -H 'accept: application/json'

有关 OpenAPI 项目的更多信息，请查阅 OpenAPI 规范。

兼容性

OpenAPI 规范自 2010 年首次创建以来经历了 3 次修订。Swagger Codegen 项目的当前稳定版本与 OpenAPI 规范具有以下兼容性：

Swagger Codegen 版本	发布日期	Swagger / OpenAPI 规范兼容性	备注
3.0.68 (当前稳定版)	2025-03-05	1.0, 1.1, 1.2, 2.0, 3.0	标签 v3.0.68
2.4.45 (当前稳定版)	2025-06-08	1.0, 1.1, 1.2, 2.0	标签 v2.4.45

💁 以下是即将推出的概览

Swagger Codegen 版本	发布日期	Swagger / OpenAPI 规范兼容性	备注
3.0.69-SNAPSHOT (当前为 3.0.0，即将推出次要版本) SNAPSHOT	待定	1.0, 1.1, 1.2, 2.0, 3.0	次要版本
2.4.46-SNAPSHOT (当前主分支，即将推出次要版本) SNAPSHOT	待定	1.0, 1.1, 1.2, 2.0	次要版本

有关所有版本的详细分类，请参阅完整兼容性列表。

开始使用

要开始使用 Swagger Codegen，请查看以下指南和说明

环境设置完成后，您就可以开始生成客户端和/或服务器了。

举个简单的例子，要为 Swagger Petstore 生成一个 PHP 客户端，请运行以下命令：

1
git clone https://github.com/swagger-api/swagger-codegen
2
cd swagger-codegen
3
git checkout 3.0.0
4
mvn clean package
5
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
6
   -i http://petstore.swagger.io/v2/swagger.json \
7
   -l php \
8
   -o /var/tmp/php_api_client

注意：如果您使用 Windows，请将最后一条命令替换为：

1
java -jar modules\swagger-codegen-cli\target\swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l php -o c:\temp\php_api_client

您也可以直接从 maven.org 下载 JAR（最新版本）。

要获取可用常规选项的列表，请运行：

1
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate --help

要获取 PHP 特定选项的列表（可通过 -c 选项的配置文件传递给生成器），请运行：

1
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php

生成器

生成示例客户端库

您可以按如下方式针对 swagger 示例 petstore API 构建客户端：

1
./bin/java-petstore.sh

在 Windows 上，请运行 .\bin\windows\java-petstore.bat。

这将使用此命令运行生成器：

1
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
2
  -i http://petstore.swagger.io/v2/swagger.json \                               # The location of the Swagger specifcation file (JSON/YAML).
3
  -l java \                                                                     # The desired language for the library.
4
  -o samples/client/petstore/java                                               # The output destination.

您可以使用 generate --help 命令获取选项（下面仅显示部分结果）：

1
NAME
2
        swagger-codegen-cli generate - Generate code with chosen lang
3

4
SYNOPSIS
5
        swagger-codegen-cli generate
6
                [(-a <authorization> | --auth <authorization>)]
7
                [--additional-properties <additional properties>...]
8
                [--api-package <api package>] [--artifact-id <artifact id>]
9
                [--artifact-version <artifact version>]
10
                [(-c <configuration file> | --config <configuration file>)]
11
                [-D <system properties>...] [--git-repo-id <git repo id>]
12
                [--git-user-id <git user id>] [--group-id <group id>]
13
                [--http-user-agent <http user agent>]
14
                (-i <spec file> | --input-spec <spec file>)
15
                [--ignore-file-override <ignore file override location>]
16
                [--import-mappings <import mappings>...]
17
                [--instantiation-types <instantiation types>...]
18
                [--invoker-package <invoker package>]
19
                (-l <language> | --lang <language>)
20
                [--language-specific-primitives <language specific primitives>...]
21
                [--library <library>] [--model-name-prefix <model name prefix>]
22
                [--model-name-suffix <model name suffix>]
23
                [--model-package <model package>]
24
                [(-o <output directory> | --output <output directory>)]
25
                [--release-note <release note>] [--remove-operation-id-prefix]
26
                [--reserved-words-mappings <reserved word mappings>...]
27
                [(-s | --skip-overwrite)]
28
                [(-t <template directory> | --template-dir <template directory>)]
29
                [--type-mappings <type mappings>...] [(-v | --verbose)]
30

31
OPTIONS
32
        -a <authorization>, --auth <authorization>
33
            adds authorization headers when fetching the swagger definitions
34
            remotely. Pass in a URL-encoded string of name:header with a comma
35
            separating multiple values
36

37
...... (results omitted)
38

39
        -v, --verbose
40
            verbose mode

然后您可以编译并运行客户端，以及对其进行单元测试。

1
cd samples/client/petstore/java
2
mvn package

其他语言也有 petstore 示例。

1
./bin/android-petstore.sh
2
./bin/java-petstore.sh
3
./bin/objc-petstore.sh

从您的服务器生成库

这同样简单！使用 -i 标志指向服务器或文件。

🔧 Swagger Codegen 提供了大量的灵活性，以支持您的代码生成偏好。请查看生成器文档，其中介绍了各种可能性以及如何从本地文件生成代码。

选择性生成

您可能不想生成项目中的所有模型。同样，您可能只想编写一两个 API，甚至忽略某些文件格式。如果是这种情况，请查看选择性生成说明。

高级生成器自定义

除了创建或修改模板之外，代码生成器还有不同的自定义方面。每种语言都有一个支持配置文件来处理不同的类型映射，或者引入您自己的模型。欲了解更多信息，请查看高级配置文档。

验证您的 OpenAPI 描述

您有多种选择。最简单的方法是使用我们的在线验证器，它不仅可以验证您的 OpenAPI 文件，还可以通过调试标志查看文件中的问题。请查看Swagger Validator来验证一个 petstore 示例。

如果您想直接在自己的机器上进行验证，那么 Spectral 是一个不错的选择。

生成动态 HTML API 文档

为此，只需在读取规范文件时使用 -l dynamic-html 标志。这将创建可作为带有 AJAX 的单页应用程序提供的 HTML 文档。要查看文档：

1
cd samples/dynamic-html/
2
npm install
3
node .

它会启动一个 node.js 服务器，以便 AJAX 调用可以进行。

工作流集成

您可以直接在您偏好的 CI/CD 工作流中利用 Swagger Codegen，以简化您的自动生成需求。请查看工作流集成指南，了解我们的 Maven、Gradle 和 GitHub 集成选项。🚀

在线生成器

如果您不想运行和托管自己的代码生成实例，请查看我们的在线生成器信息。

贡献

请参阅此页面。

🚧 对于 swagger-codegen 版本 3，代码生成模板和类正在迁移到 swagger-codegen-generators 仓库。要了解此迁移过程，您可以参阅此页面。

安全联系方式

请通过电子邮件 security@swagger.io 披露任何安全相关问题或漏洞，而不是使用公共问题追踪器。

感谢

💚💚💚 我们要向所有为 Swagger Codegen 做出贡献的人致以崇高的敬意，无论是提出问题、修复错误、编写模板，还是为他人制作有用的内容。💚💚💚