Swagger Codegen

這是 Swagger Codegen 專案，可讓您根據 OpenAPI 規格自動產生 API 用戶端程式庫（SDK 產生）、伺服器存根和文件。

💚 如果您想參與貢獻，請參閱準則和開放工作清單。💚

📔 如需詳細資訊，請參閱 Wiki 頁面和 FAQ 📔

⚠️ 如果 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。
只有 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 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-18	1.0, 1.1, 1.2, 2.0, 3.0	標籤 v3.0.65
2.4.44 (目前穩定)	2024-12-18	1.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 標記即可。這會建立可作為具有 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 做出貢獻的人，無論是提出問題、修復錯誤、編寫範本，還是為他人撰寫有用的內容。💚💚💚