跳过内容

Swagger Codegen

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

💚 如果您想做出贡献，请参阅贡献指南和待解决任务列表。💚

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

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

版本控制

⚠️ 本文档涉及2.X版本，请此处查看3.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客户端: ActionScript, Ada, Apex, Bash, C# (.net 2.0, 3.5 or later), C++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell (http-client, Servant), Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-assured), Kotlin, Lua, Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations) Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust (rust, rust-server), Scala (akka, http4s, swagger-async-httpclient), Swift (2.x, 3.x, 4.x, 5.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
  • 服务器存根: Ada, C# (ASP.NET Core, NancyFx), C++ (Pistache, Restbed), Erlang, Go, Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy, Play Framework, PKMST), Kotlin, PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), Rust (rust-server), Scala (Finch, Lagom, Scalatra)
  • API文档生成器: HTML, Confluence Wiki
  • 配置文件: Apache2
  • 其他: JMeter

请查看OpenAPI规范以获取有关OpenAPI项目的更多信息。

兼容性

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

Swagger Codegen 版本发布日期Swagger / OpenAPI 规范兼容性备注
3.0.68 (当前稳定版)2025-03-051.0, 1.1, 1.2, 2.0, 3.0标签 v3.0.68
2.4.45 (当前稳定版)2025-06-081.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 (当前 master，即将发布的次要版本) SNAPSHOT待定1.0, 1.1, 1.2, 2.0次要版本

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

开始入门

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

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

举个简单的例子，要为https://petstore.swagger.io/v2/swagger.json生成PHP客户端，您可以运行以下命令：

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

注意：如果您在Windows上，请将最后一个命令替换为：

终端窗口
1
java -jar modules\swagger-codegen-cli\target\swagger-codegen-cli.jar generate -i https://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 help generate

要获取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 https://petstore.swagger.io/v2/swagger.json \
3
  -l java \
4
  -o samples/client/petstore/java

附带多个选项。您可以使用help generate命令获取这些选项（下文仅显示部分结果）：

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规范

您有多种选择。最简单的方法是使用我们的在线验证器，它不仅可以验证您的规范，还可以通过调试标志查看规范中的问题。例如，请查看Swagger验证器。

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

生成动态HTML API文档

为此，只需在读取规范文件时使用-l dynamic-html标志。这将创建可作为单页应用程序（带AJAX）的HTML文档。要查看文档，请执行以下操作：

终端窗口
1
cd samples/dynamic-html/
2
npm install
3
node .

这将启动一个Node.js服务器，以便AJAX调用能够正常进行。

生成静态HTML API文档

为此，只需在读取规范文件时使用-l html标志。这将创建一个包含嵌入式CSS的简单HTML文件，您可以将其作为电子邮件附件发送，或从文件系统加载。

终端窗口
1
cd samples/html/
2
open index.html

工作流集成

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

在线生成器

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

贡献

请参阅此页面

安全联系方式

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

感谢

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

© . All rights reserved.