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。
仅 3.X 版本支持 OpenAPI 3.0.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 项目的更多信息。

兼容性

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

Swagger Codegen 版本	发布日期	Swagger / OpenAPI 规范兼容性	备注
3.0.66 (当前稳定版)	2024-12-23	1.0, 1.1, 1.2, 2.0, 3.0	标签 v3.0.66
2.4.44 (当前稳定版)	2024-12-18	1.0, 1.1, 1.2, 2.0	标签 v2.4.44

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

Swagger Codegen 版本	发布日期	Swagger / OpenAPI 规范兼容性	备注
3.0.67-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，请查看以下指南和说明

一旦您设置好环境，就可以开始生成客户端和/或服务器。

作为一个简单的示例，要为 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 验证器来验证 petstore 示例。

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

生成动态 html api 文档

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

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

它会启动一个 node.js 服务器，以便 AJAX 调用有一个去处。

工作流集成

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

在线生成器

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

贡献

请参考此页面。

🚧 对于 swagger-codegen version 3，代码生成的模板和类正在迁移到 swagger-codegen-generators 存储库。为了解此迁移过程，您可以参考此页面。

安全联系人

请通过发送电子邮件至 [email protected] 来披露任何与安全相关的问题或漏洞，而不是使用公共问题跟踪器。

感谢

💚💚💚 我们衷心感谢所有为 Swagger Codegen 做出贡献的人，无论是提出问题、修复错误、编写模板，还是为他人撰写有用的内容。💚💚💚