招搖代碼產生器
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 、 Erzen 、 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 程式碼產生版本 | 發布日期 | 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 做出貢獻的人表示大力的讚揚，無論是提出問題、修復錯誤、創作模板還是製作有用的內容以供其他人從中受益。
