招摇代码生成器
Swagger
这是 Swagger Codegen 项目，它允许根据 OpenAPI 规范自动生成 API 客户端库（SDK 生成）、服务器存根和文档。
如果您想做出贡献，请参阅指南和开放任务列表。
欲了解更多信息，请参阅 Wiki 页面和 FAQ ?
⚠️ 本文档指的是2.X版本，3.X请在此处查看。
Swagger Codegen 的2.X和3.X版本系列均可用且独立维护。
笔记：
版本 2.X ( io.swagger ) 和 3.X ( io.swagger.codegen.v3 ) 有不同的组 id。
仅 3.X 版本支持 OpenAPI 3.0.X。
有关完整的版本控制信息，请参阅版本控制文档。
目前支持以下语言/框架：
API 客户端： ActionScript 、 Ada 、 Apex 、 Bash 、 C# （.net 2.0、3.5 或更高版本）、 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 Java 客户端库, Rest-assured), Kotlin , Lua , Node.js （带有 Google Closure 编译器注释的 ES5、ES6、AngularJS） 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,斯卡拉特拉）
API 文档生成器： HTML 、 Confluence Wiki
配置文件： Apache2
其他： JMeter
查看 OpenAPI-Spec 以获取有关 OpenAPI 项目的更多信息。
版本控制
兼容性
入门
发电机
生成示例客户端库
从您的服务器生成库
验证您的 OpenAPI 规范
生成动态html api文档
生成静态html api文档
工作流程集成
在线生成器
贡献
Swagger Codegen 核心团队
自 2010 年首次创建以来，OpenAPI 规范已经历了 3 次修订。Swagger Codegen 项目当前的稳定版本与 OpenAPI 规范具有以下兼容性：
| Swagger 代码生成版本 | 发布日期 | Swagger / OpenAPI 规范兼容性 | 笔记 |
|---|---|---|---|
| 3.0.62（当前稳定） | 2024-08-27 | 1.0、1.1、1.2、2.0、3.0 | 标签 v3.0.62 |
| 2.4.43（当前稳定） | 2024-08-09 | 1.0、1.1、1.2、2.0 | 标签 v2.4.42 |
以下也是即将发生的事情的概述：
| Swagger 代码生成版本 | 发布日期 | Swagger / OpenAPI 规范兼容性 | 笔记 |
|---|---|---|---|
| 3.0.63-SNAPSHOT（当前 3.0.0，即将发布的次要版本）SNAPSHOT | 待定 | 1.0、1.1、1.2、2.0、3.0 | 次要版本 |
| 2.4.44-SNAPSHOT（当前主版本，即将发布的次要版本）SNAPSHOT | 待定 | 1.0、1.1、1.2、2.0 | 次要版本 |
有关所有版本的详细分类，请参阅完整的兼容性列表。
要启动并运行 Swagger Codegen，请查看以下指南和说明：
先决条件
建筑
使用 Docker
设置好环境后，您就可以开始生成客户端和/或服务器了。
举个简单的例子，要为 https://petstore.swagger.io/v2/swagger.json 生成 PHP 客户端，您可以运行以下命令：
git 克隆 https://github.com/swagger-api/swagger-codegencd swagger-codegen
mvn清理包
java -jar 模块/swagger-codegen-cli/target/swagger-codegen-cli.jar 生成
-i https://petstore.swagger.io/v2/swagger.json
-l php
-o /var/tmp/php_api_client注意：如果您使用的是 Windows，请将最后一个命令替换为
java -jar moduleswagger-codegen-clitargetswagger-codegen-cli.jar 生成 -i https://petstore.swagger.io/v2/swagger.json -l php -o c:tempphp_api_client
您还可以直接从 maven.org 下载 JAR（最新版本）
要获取可用的常规选项列表，您可以运行以下命令：
java -jar module/swagger-codegen-cli/target/swagger-codegen-cli.jar 帮助生成
要获取 PHP 指定选项的列表（可以通过-c选项将配置文件传递给生成器），请运行
java -jar 模块/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php
您可以根据 swagger 示例 petstore API 构建客户端，如下所示：
./bin/java-petstore.sh
（在 Windows 上，运行.binwindowsjava-petstore.bat ）
这将使用以下命令运行生成器：
java -jar 模块/swagger-codegen-cli/target/swagger-codegen-cli.jar 生成 -i https://petstore.swagger.io/v2/swagger.json -l java -o 样本/客户端/petstore/java
有多种选择。您可以使用help generate命令获取选项（下面仅显示部分结果）：
NAME
swagger-codegen-cli generate - Generate code with chosen lang
SYNOPSIS
swagger-codegen-cli generate
[(-a | --auth )]
[--additional-properties ...]
[--api-package ] [--artifact-id ]
[--artifact-version ]
[(-c | --config )]
[-D ...] [--git-repo-id ]
[--git-user-id ] [--group-id ]
[--http-user-agent ]
(-i | --input-spec )
[--ignore-file-override ]
[--import-mappings ...]
[--instantiation-types ...]
[--invoker-package ]
(-l | --lang )
[--language-specific-primitives ...]
[--library ] [--model-name-prefix ]
[--model-name-suffix ]
[--model-package ]
[(-o | --output )]
[--release-note ] [--remove-operation-id-prefix]
[--reserved-words-mappings ...]
[(-s | --skip-overwrite)]
[(-t | --template-dir )]
[--type-mappings ...] [(-v | --verbose)]
OPTIONS
-a , --auth
adds authorization headers when fetching the swagger definitions
remotely. Pass in a URL-encoded string of name:header with a comma
separating multiple values
...... (results omitted)
-v, --verbose
verbose mode 然后，您可以编译并运行客户端，并对其进行单元测试：
cd 示例/客户端/petstore/java MVN包
其他语言也有 petstore 示例：
./bin/android-petstore.sh ./bin/java-petstore.sh ./bin/objc-petstore.sh
这也很简单——只需使用-i标志来指向服务器或文件。
？ Swagger Codegen 具有极大的灵活性来支持您的代码生成首选项。查看生成器文档，它会带您了解一些可能性，并展示如何从本地文件生成并忽略文件格式。
您可能不想生成项目中的所有模型。 同样，您可能只需要编写一两个 api。如果是这种情况，请检查选择性生成说明。
除了创建或修改模板之外，自定义代码生成器还有不同的方面。 每种语言都有一个支持配置文件来处理不同的类型映射，或带来您自己的模型。有关更多信息，请查看高级配置文档。
你有选择。 最简单的方法是使用我们的在线验证器，它不仅可以让您验证您的规范，而且通过调试标志，您可以看到您的规范有什么问题。 例如，查看 Swagger 验证器。
如果您想直接在自己的机器上进行验证，那么 Spectral 是一个很好的选择。
为此，只需在读取规范文件时使用-l dynamic-html标志即可。 这将创建可作为 AJAX 的单页应用程序使用的 HTML 文档。 要查看文档：
cd 样本/dynamic-html/ npm 安装 节点 .
它会启动一个 Node.js 服务器，以便 AJAX 调用有地方可去。
为此，只需在读取规范文件时使用-l html标志即可。 这将创建一个带有嵌入式 css 的单个简单 HTML 文件，以便您可以将其作为电子邮件附件发送，或从文件系统加载它：
cd 样本/html/ 打开索引.html
可以在您首选的 CI/CD 工作流程中直接利用 Swagger Codegen 来简化您的自动生成需求。查看工作流程集成指南，了解有关 Maven、Gradle 和 GitHub 集成选项的信息。 ？
如果您不想运行和托管自己的代码生成实例，请检查我们的在线生成器信息。
请参考这个页面
Swagger Codegen 核心团队成员是定期为项目做出重大贡献（审查问题、修复错误、增强功能等）的贡献者。
核心团队成员承担以下职责：
为其他用户提供指导和方向
审查拉取请求和问题
通过增强、修复错误或更新文档来改进生成器
设定生成器的技术方向
请通过发送电子邮件至 [email protected] 来披露任何与安全相关的问题或漏洞，而不是使用公共问题跟踪器。
Swagger Codegen 项目旨在为 Swagger/开放 API 规范的用户带来好处。 该项目本身具有指定的许可证。 此外，还请您了解以下几点：
该项目中包含的模板受许可证约束。
生成的代码有意不受父项目许可证的约束
当从该项目生成代码时，它应被视为按原样并由软件用户拥有。 对于生成的代码不提供任何明示或暗示的保证。 您可以用它做您想做的事情，一旦生成，代码就是您的责任，并受您认为适当的许可条款的约束。
我们要向所有为 Swagger Codegen 做出贡献的人表示大力的赞扬，无论是提出问题、修复错误、创作模板还是制作有用的内容以供其他人从中受益。
