跳到内容

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 或更高版本)、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、带有 Google Closure Compiler 注释的 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、Scalatra)
  • API 文档生成器：HTML、Confluence Wiki
  • 配置文件：Apache2
  • 其他：JMeter

查看 OpenAPI-Spec 获取有关 OpenAPI 项目的更多信息。

兼容性

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

Swagger Codegen 版本发布日期Swagger / OpenAPI 规范兼容性备注
3.0.65（当前稳定版）2024-12-181.0, 1.1, 1.2, 2.0, 3.0标签 v3.0.65
2.4.44（当前稳定版）2024-12-181.0, 1.1, 1.2, 2.0标签 v2.4.44

💁 这里还有即将推出的功能的概述

Swagger Codegen 版本发布日期Swagger / OpenAPI 规范兼容性备注
3.0.66-SNAPSHOT（当前 3.0.0，即将发布的小版本）SNAPSHOT待定1.0, 1.1, 1.2, 2.0, 3.0小版本发布
2.4.45-SNAPSHOT（当前主版本，即将发布的小版本）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 标志。这将创建一个 HTML 文档，该文档作为具有 AJAX 的单页应用程序提供。要查看文档

终端窗口
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 做出贡献的人表示衷心的感谢，无论他们是提出问题、修复错误、编写模板，还是为他人编写有用的内容。💚💚💚

Swagger 开源
Swagger
专业工具
资源