Skip to content

Swagger Codegen Online Generators

swagger-generator module exposes codegen as a web service, with it’s own swagger-js based web UI, and available docker image swaggerapi/swagger-generator-v3.

The web service is deployed at https://generator3.swagger.io/ui, or it can be easily deployed as docker container.

The OpenAPI specification of generator service APIs are available either via UI exposed by web service (e.g. https://generator3.swagger.io/ui), as exposed YAML (https://generator3.swagger.io/openapi.json) or in source code repo (https://github.com/swagger-api/swagger-codegen/blob/3.0.0/modules/swagger-generator/src/main/resources/openapi.yaml).

Please note that both V2 (for v2 specs) and V3 generators (for v3 and v2 specs converted during generation) are supported, by providing property codegenVersion (e.g "codegenVersion" : "v3").

For example, to generate a java API client, simply send the following HTTP request using curl:

Terminal window
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
}'

The response will contain a zipped file containing the generated code.

To customize the SDK, you can specify language specific options with the following HTTP body:

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
}

in which the options additionalProperties for a language can be obtained by submitting a GET request to https://generator3.swagger.io/api/options?language={language}&version={codegenVersion}:

For example, curl https://generator3.swagger.io/api/options?language=java&version=V3 returns (truncated output):

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
  ...

Instead of using specURL with an URL to the OpenAPI/Swagger spec, one can include the spec in the JSON payload with spec, e.g.

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