OpenAPI Generator

https://openapi-generator.tech/docs
Admin
OpenAPI Generator is a powerful command-line tool and library that generates API clients, servers,...
Tokens:214,699
Snippets:1,542
Trust Score:9.9
Update:10 hours ago
Show doc for...
Tokens:
Raw
### Install Java via Scoop java bucket

Source: https://openapi-generator.tech/docs/installation/

Adds the Scoop java bucket and installs OpenJDK, needed if Java is not already installed.

```bash
scoop bucket add java
scoop install openjdk
```

--------------------------------

### YAML config file example

Source: https://openapi-generator.tech/docs/customization/

Equivalent YAML configuration file for Java with the same settings as the JSON example.

```yaml
groupId: "com.my.company"
artifactId: "MyClient"
artifactVersion: "1.2.0"
library: "feign"
```

--------------------------------

### Install markserv for markdown preview

Source: https://openapi-generator.tech/docs/new-generator/

Installs the markserv npm package globally to serve and preview markdown output locally, useful for testing generated documentation links.

```bash
npm install --global markserv
```

--------------------------------

### Install Bash Launcher Script for openapi-generator-cli

Source: https://openapi-generator.tech/docs/installation/

Sets up the launcher script in ~/bin/openapitools and adds it to PATH. Always evaluate scripts curled from external systems before executing.

```bash
mkdir -p ~/bin/openapitools
curl https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/bin/utils/openapi-generator-cli.sh > ~/bin/openapitools/openapi-generator-cli
chmod u+x ~/bin/openapitools/openapi-generator-cli
export PATH=$PATH:~/bin/openapitools/
```

--------------------------------

### GET options for Python generator

Source: https://openapi-generator.tech/docs/online/

Example response from GET /api/gen/clients/python showing available options like packageName, packageVersion, and sortParamsByRequiredFlag with their defaults. The response is a JSON object listing each option's metadata.

```json
  "packageName":{
    "opt":"packageName",
    "description":"python package name (convention: snake_case).",
    "type":"string",
    "default":"openapi_client"
  },
  "packageVersion":{
    "opt":"packageVersion",
    "description":"python package version.",
    "type":"string",
    "default":"1.0.0"
  },
  "sortParamsByRequiredFlag":{
    "opt":"sortParamsByRequiredFlag",
    "description":"Sort method arguments to place required parameters before optional parameters.",
    "type":"boolean",
    "default":"true"
  }

{}
```

--------------------------------

### Serve output directory with markserv

Source: https://openapi-generator.tech/docs/new-generator/

Starts a local server to preview the generated markdown documentation and test relative links.

```bash
markserv samples/documentation/petstore/common/markdown
```

--------------------------------

### OpenAPI spec: /tmp/alias.yaml used with schema mapping example

Source: https://openapi-generator.tech/docs/customization/

This OpenAPI 3.0.3 specification defines a GET /demo endpoint returning a text/csv response with a binary string schema. It is the input file referenced by the preceding --schema-mappings example.

```yaml
openapi: 3.0.3
info:
  title: Demo app
  version: 1.0.0
servers:
  - url: /api/v1
paths:
  /demo:
    get:
      summary: Demo
      operationId: demo
      responses:
        '200':
          description: Demo response
          content:
            text/csv:
              schema:
                type: string
                format: binary
```

--------------------------------

### new.sh help output

Source: https://openapi-generator.tech/docs/new-generator/

Shows usage and options for the new.sh script, including flags for generator types and test file creation. Run ./new.sh --help to see this.

```text
Stubs out files for new generators

Usage:
./new.sh [options]
    Options:
    -n  Required. Specify generator name, should be kebab-cased.
    -c  Create a client generator
    -s  Create a server generator
    -d  Create a documentation generator
    -H  Create a schema generator
    -f  Create a config generator
    -t  When specified, creates test file(s) for the generator.
    -h  Display help.

Examples:
  Create a server generator for ktor:
  ./new.sh -n kotlin -s

    Creates:
    modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinServerCodegen.java
    modules/openapi-generator/src/main/resources/kotlin-server/README.mustache
    modules/openapi-generator/src/main/resources/kotlin-server/model.mustache
    modules/openapi-generator/src/main/resources/kotlin-server/api.mustache
    bin/configs/kotlin-server-petstore-new.yaml

  Create a generic C# server generator:
  ./new.sh -n csharp -s -t
    Creates:
    modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/CsharpServerCodegen.java
    modules/openapi-generator/src/main/resources/csharp-server/README.mustache
    modules/openapi-generator/src/main/resources/csharp-server/model.mustache
    modules/openapi-generator/src/main/resources/csharp-server/api.mustache
    bin/configs/csharp-server-petstore-new.yaml
    modules/openapi-generator/src/test/java/org/openapitools/codegen/csharp/CsharpServerCodegenTest.java
    modules/openapi-generator/src/test/java/org/openapitools/codegen/csharp/CsharpServerCodegenModelTest.java
    modules/openapi-generator/src/test/java/org/openapitools/codegen/csharp/CsharpServerCodegenOptionsTest.java
    modules/openapi-generator/src/test/java/org/openapitools/codegen/options/CsharpServerCodegenOptionsProvider.java

```

--------------------------------

### Generate Go client using Docker image

Source: https://openapi-generator.tech/docs/installation/

Runs the OpenAPI Generator Docker image to generate a Go client from a petstore.yaml file. Mounts the current directory to /local and outputs to /local/out/go.

```bash
docker run --rm \
  -v ${PWD}:/local openapitools/openapi-generator-cli generate \
  -i /local/petstore.yaml \
  -g go \
  -o /local/out/go
```

--------------------------------

### 1-based index with {{-index}}

Source: https://openapi-generator.tech/docs/templating/

Use {{-index}} to get a 1-based index during array traversal. The example prints the index followed by the enum value.

```mustache
{{#enums}}{{-index}} {{enum}}{{/enums}}
```

--------------------------------

### x-response-id example for Rust-server

Source: https://openapi-generator.tech/docs/templating/

Names the enum variant for a response in rust-server. Each response may specify a unique x-response-id; here the 200 response gets the variant Pong.

```yaml
paths:
  /ping:
    get:
      responses:
        200:
          description: OK
          x-response-id: Pong
```

--------------------------------

### Run integration tests with Maven

Source: https://openapi-generator.tech/docs/contributing/

Run integration tests in a sample folder using Maven. A local Petstore server instance is required; running against petstore.swagger.io is not supported.

```bash
mvn integration-test -f /path/to/pom.xml
```

```bash
mvn integration-test -f samples/client/petstore/python/pom.xml
```

--------------------------------

### Example OpenAPI spec document (Swagger Petstore)

Source: https://openapi-generator.tech/docs/templating/

Sample OpenAPI 2.0 specification used to illustrate the data structures available to templates. Defines a /pets path with a GET operation and a Pet model with id, name, and tag properties.

```yaml
  swagger: "2.0"
  info:
    version: "1.0.0"
    title: "Swagger Petstore"
    description: "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification"
    termsOfService: "http://swagger.io/terms/"
    contact:
      name: "Swagger API Team"
    license:
      name: "MIT"
  host: "petstore.swagger.io"
  basePath: "/api"
  schemes:
    - "http"
  consumes:
    - "application/json"
  produces:
    - "application/json"
  paths:
    /pets:
      get:
        description: "Returns all pets from the system that the user has access to"
        produces:
          - "application/json"
        responses:
          "200":
            description: "A list of pets."
            schema:
              type: "array"
              items:
                $ref: "#/definitions/Pet"
  definitions:
    Pet:
      type: "object"
      required:
        - "id"
        - "name"
      properties:
        id:
          type: "integer"
          format: "int64"
        name:
          type: "string"
        tag:
          type: "string"
```

--------------------------------

### Generate Ruby client from petstore.yaml

Source: https://openapi-generator.tech/docs/installation/

Generates a Ruby client from a valid petstore.yaml document using the CLI. The npx command executes a globally available openapi-generator, falling back to project-local commands if not found.

```bash
npx @openapitools/openapi-generator-cli generate -i petstore.yaml -g ruby -o /tmp/test/
```

--------------------------------

### Install OpenAPI Generator via Homebrew (macOS)

Source: https://openapi-generator.tech/docs/installation/

Installs the OpenAPI Generator CLI on macOS using Homebrew. Requires Homebrew to be installed.

```bash
brew install openapi-generator
```

--------------------------------

### config-help output for Java

Source: https://openapi-generator.tech/docs/customization/

Example output from config-help -g java showing available options and library choices. The library option lists supported sub-templates with their HTTP clients and JSON processing libraries.

```bash
CONFIG OPTIONS
    modelPackage
        package for generated models

    apiPackage
        package for generated api classes
...... (results omitted)
    library
        library template (sub-template) to use:
        jersey2 - HTTP client: Jersey client 2.6
        feign - HTTP client: Netflix Feign 8.1.1.  JSON processing: Jackson 2.6.3
        okhttp-gson (default) - HTTP client: OkHttp 2.4.0. JSON processing: Gson 2.3.1
        retrofit - HTTP client: OkHttp 2.4.0. JSON processing: Gson 2.3.1 (Retrofit 1.9.0)
        retrofit2 - HTTP client: OkHttp 2.5.0. JSON processing: Gson 2.4 (Retrofit 2.0.0-beta2)
        google-api-client - HTTP client: google-api-client 1.23.0. JSON processing: Jackson 2.8.9
        rest-assured - HTTP client: rest-assured : 4.3.0. JSON processing: Gson 2.8.6. Only for Java8
```

--------------------------------

### Install OpenAPI Generator CLI via Scoop (Windows)

Source: https://openapi-generator.tech/docs/installation/

Installs the OpenAPI Generator CLI on Windows using Scoop. Requires Scoop to be installed.

```bash
scoop install openapi-generator-cli
```

--------------------------------

### Install OpenAPI Generator CLI via PyPI

Source: https://openapi-generator.tech/docs/installation/

Installs the OpenAPI Generator CLI from PyPI. Requires a Java executable to run.

```bash
pip install openapi-generator-cli
```

--------------------------------

### Install OpenAPI Generator CLI as dev dependency

Source: https://openapi-generator.tech/docs/installation/

Installs the CLI tool as a dev dependency in the current project, making it available for project-local use.

```bash
npm install @openapitools/openapi-generator-cli -D
```
Tokens:
Raw