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 儲存庫。為了解此遷移過程，您可以參考此頁面。

安全性聯絡人

請透過電子郵件 security@swagger.io 揭露任何與安全相關的問題或漏洞，而不是使用公開的問題追蹤器。

感謝您

💚💚💚 我們要向所有為 Swagger Codegen 做出貢獻的人致上最高的敬意，無論是提出問題、修復錯誤、編寫範本，或是為其他人製作有用的內容。💚💚💚