Swagger Codegen 線上產生器

swagger-generator 模組將程式碼產生器公開為 Web 服務，具有自己的以 swagger-js 為基礎的 Web UI，並提供可用的 Docker 映像 swaggerapi/swagger-generator-v3。

Web 服務部署於 https://generator3.swagger.io/ui，也可以輕鬆部署為 Docker 容器。

產生器服務 API 的 OpenAPI 規格可透過 Web 服務公開的 UI（例如 https://generator3.swagger.io/ui）、公開的 YAML (https://generator3.swagger.io/openapi.json) 或原始碼儲存庫 (https://github.com/swagger-api/swagger-codegen/blob/3.0.0/modules/swagger-generator/src/main/resources/openapi.yaml) 取得。

請注意，V2（適用於 v2 規格）和 V3 產生器（適用於 v3 和在產生期間轉換的 v2 規格）都支援，方法是提供屬性 codegenVersion（例如 "codegenVersion" : "v3"）。

例如，若要產生 Java API 用戶端，只需使用 curl 發送以下 HTTP 請求

1
curl -X POST \
2
  https://generator3.swagger.io/api/generate \
3
  -H 'content-type: application/json' \
4
  -d '{
5
  "specURL" : "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml",
6
  "lang" : "java",
7
  "type" : "CLIENT",
8
  "codegenVersion" : "V3"
9
}'

回應將包含一個包含產生程式碼的壓縮檔案。

若要自訂 SDK，您可以使用以下 HTTP 主體指定語言特定的選項

1
{
2
  "specURL" : "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml",
3
  "lang" : "java",
4
  "options" : {
5
    "additionalProperties" : {
6
    "useRuntimeException": true,
7
    "useRxJava" : true
8
    }
9
  },
10
  "type" : "CLIENT",
11
  "codegenVersion" : "V3"
12
}

其中可以透過向 https://generator3.swagger.io/api/options?language={language}&version={codegenVersion} 提交 GET 請求來取得語言的 options additionalProperties

例如，curl https://generator3.swagger.io/api/options?language=java&version=V3 返回（截斷的輸出）

1
{
2
  "sortParamsByRequiredFlag": {
3
    "opt": "sortParamsByRequiredFlag",
4
    "description": "Sort method arguments to place required parameters before optional parameters.",
5
    "type": "boolean",
6
    "default": "true"
7
  },
8
  "ensureUniqueParams": {
9
    "opt": "ensureUniqueParams",
10
    "description": "Whether to ensure parameter names are unique in an operation (rename parameters that are not).",
11
    "type": "boolean",
12
    "default": "true"
13
  },
14
  "allowUnicodeIdentifiers": {
15
    "opt": "allowUnicodeIdentifiers",
16
    "description": "boolean, toggles whether unicode identifiers are allowed in names or not, default is false",
17
    "type": "boolean",
18
    "default": "false"
19
  },
20
  "modelPackage": {
21
    "opt": "modelPackage",
22
    "description": "package for generated models",
23
    "type": "string"
24
  },
25
  ...

除了使用包含 OpenAPI/Swagger 規格的 URL 的 specURL 外，還可以將規格包含在 JSON 有效負載中，使用 spec，例如

1
{
2
  "options": {},
3
  "spec": {
4
    "swagger": "2.0",
5
    "info": {
6
      "version": "1.0.0",
7
      "title": "Test API"
8
    },
9
    ...
10
  }
11
}