OpenAPI JSON Schema Generator allows auto-generation of API client libraries with a focus on JSON schema given an OpenAPI Spec

Last update: Dec 31, 2022

Overview

OpenAPI JSON Schema Generator

IMPORTANT: before the first release, one will need to build the project locally to use the enhancements, bug fixes in the latest master

⭐ ⭐ ⭐ If you would like to contribute, please refer to guidelines and a list of open tasks. ⭐ ⭐ ⭐

⚠️ If the OpenAPI spec, templates or any input (e.g. options, environment variables) is obtained from an untrusted source or environment, please make sure you've reviewed these inputs before using OpenAPI JSON Schema Generator to generate the API client, server stub or documentation to avoid potential security issues (e.g. code injection). For security vulnerabilities, please contact [email protected]. ⚠️

‼️ Both "OpenAPI Tools" (https://OpenAPITools.org - the parent organization of OpenAPI JSON Schema Generator) and "OpenAPI JSON Schema Generator" are not affiliated with OpenAPI Initiative (OAI) ‼️

Overview

OpenAPI JSON Schema Generator allows auto-generation of API client libraries (SDK generation) with a focus on JSON Schema given an OpenAPI Spec (3.0 are supported). Currently, the following languages/frameworks are supported:

python

Why this repo exists

This repo is based on v6.2.0 of OpenAPI Generator. This project focuses on making the output 100% compliant with JSON schema as part of the OpenAPI 3.1 specification with a focus on complex cases (top-down approach). The goal is to fully support everything defined in JSON schema so that developers can leverage JSON schema as well as OpenAPI specification in their API design. Building here allows for more rapid progress supporting new features in OpenAPI 3.X without having to support many older generators which don't use the new features.

OpenAPI JSON Schema Generator
Overview
Table of Contents
1 - Installation
2 - Getting Started
3 - Usage
4 - Companies/Projects using OpenAPI JSON Schema Generator
5 - About Us
- 5.3 - History of OpenAPI JSON Schema Generator
6 - License

1 - Installation

1.1 - Compatibility

The OpenAPI Specification has undergone 3 revisions since initial creation in 2010. The openapi-json-schema-generator project has the following compatibilities with the OpenAPI Specification:

OpenAPI JSON Schema Generator Version	Release Date	Notes
1.0.0 (first stable release) SNAPSHOT	TBD	First release
OpenAPI Spec compatibility: 3.0

1.2 - Artifacts on Maven Central

You can find our released artifacts on maven central:

Core:

<dependency>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-json-schema-generator</artifactId>
    <version>${openapi-json-schema-generator-version}</version>
</dependency>

See the different versions of the openapi-json-schema-generator artifact available on maven central.

Cli:

<dependency>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-json-schema-generator-cli</artifactId>
    <version>${openapi-json-schema-generator-version}</version>
</dependency>

See the different versions of the openapi-json-schema-generator-cli artifact available on maven central.

Maven plugin:

<dependency>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-json-schema-generator-maven-plugin</artifactId>
    <version>${openapi-json-schema-generator-version}</version>
</dependency>

See the different versions of the openapi-json-schema-generator-maven-plugin artifact available on maven central.
Readme

Gradle plugin:

<dependency>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-json-schema-generator-gradle-plugin</artifactId>
    <version>${openapi-json-schema-generator-version}</version>
</dependency>

See the different versions of the openapi-json-schema-generator-gradle-plugin artifact available on maven central.
Readme

1.3 - Download JAR

If you're looking for the latest stable version, you can grab it directly from Maven.org (Java 8 runtime at a minimum):

JAR location: https://repo1.maven.org/maven2/org/openapitools/openapi-json-schema-generator-cli/6.1.0/openapi-json-schema-generator-cli-6.1.0.jar

For Mac/Linux users:

wget https://repo1.maven.org/maven2/org/openapitools/openapi-json-schema-generator-cli/6.1.0/openapi-json-schema-generator-cli-6.1.0.jar -O openapi-json-schema-generator-cli.jar

For Windows users, you will need to install wget or you can use Invoke-WebRequest in PowerShell (3.0+), e.g.

Invoke-WebRequest -OutFile openapi-json-schema-generator-cli.jar https://repo1.maven.org/maven2/org/openapitools/openapi-json-schema-generator-cli/6.1.0/openapi-json-schema-generator-cli-6.1.0.jar

After downloading the JAR, run java -jar openapi-json-schema-generator-cli.jar help to show the usage.

For Mac users, please make sure Java 8 is installed (Tips: run java -version to check the version), and export JAVA_HOME in order to use the supported Java version:

export JAVA_HOME=`/usr/libexec/java_home -v 1.8`
export PATH=${JAVA_HOME}/bin:$PATH

1.4 - Build Projects

To build from source, you need the following installed and available in your $PATH:

After cloning the project, you can build it from source with this command:

mvn clean install

If you don't have maven installed, you may directly use the included maven wrapper, and build with the command:

./mvnw clean install

The default build contains minimal static analysis (via CheckStyle). To run your build with PMD and Spotbugs, use the static-analysis profile:

mvn -Pstatic-analysis clean install

1.6 - Docker

Public Pre-built Docker images

https://hub.docker.com/r/openapitools/openapi-json-schema-generator-cli/ (official CLI)
https://hub.docker.com/r/openapitools/openapi-json-schema-generator-online/ (official web service)

OpenAPI JSON Schema Generator CLI Docker Image

The OpenAPI JSON Schema Generator image acts as a standalone executable. It can be used as an alternative to installing via homebrew, or for developers who are unable to install Java or upgrade the installed version.

To generate code with this image, you'll need to mount a local location as a volume.

Example:

docker run --rm -v "${PWD}:/local" openapitools/openapi-json-schema-generator-cli generate \
    -i https://raw.githubusercontent.com/openapitools/openapi-json-schema-generator/master/modules/openapi-json-schema-generator/src/test/resources/3_0/petstore.yaml \
    -g python \
    -o /local/out/python

The generated code will be located under ./out/python in the current directory.

OpenAPI JSON Schema Generator Online Docker Image

The openapi-json-schema-generator-online image can act as a self-hosted web application and API for generating code. This container can be incorporated into a CI pipeline, and requires at least two HTTP requests and some docker orchestration to access generated code.

Example usage:

# Start container at port 8888 and save the container id
> CID=$(docker run -d -p 8888:8080 openapitools/openapi-json-schema-generator-online)

# allow for startup
> sleep 10

# Get the IP of the running container (optional)
GEN_IP=$(docker inspect --format '{{.NetworkSettings.IPAddress}}'  $CID)

# Execute an HTTP request to generate a Ruby client
> curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-json-schema-generator/master/modules/openapi-json-schema-generator/src/test/resources/3_0/petstore.yaml"}' \
'http://localhost:8888/api/gen/clients/python'

{"code":"c2d483.3.4672-40e9-91df-b9ffd18d22b8","link":"http://localhost:8888/api/gen/download/c2d483.3.4672-40e9-91df-b9ffd18d22b8"}

# Download the generated zip file
> wget http://localhost:8888/api/gen/download/c2d483.3.4672-40e9-91df-b9ffd18d22b8

# Unzip the file
> unzip c2d483.3.4672-40e9-91df-b9ffd18d22b8

# Shutdown the openapi generator image
> docker stop $CID && docker rm $CID

Development in docker

You can use run-in-docker.sh to do all development. This script maps your local repository to /gen in the docker container. It also maps ~/.m2/repository to the appropriate container location.

To execute mvn package:

git clone https://github.com/openapitools/openapi-json-schema-generator
cd openapi-json-schema-generator
./run-in-docker.sh mvn package

Build artifacts are now accessible in your working directory.

Once built, run-in-docker.sh will act as an executable for openapi-json-schema-generator-cli. To generate code, you'll need to output to a directory under /gen (e.g. /gen/out). For example:

./run-in-docker.sh help # Executes 'help' command for openapi-json-schema-generator-cli
./run-in-docker.sh list # Executes 'list' command for openapi-json-schema-generator-cli
./run-in-docker.sh /gen/bin/python-petstore.sh  # Builds the Go client
./run-in-docker.sh generate -i modules/openapi-json-schema-generator/src/test/resources/3_0/petstore.yaml \
    -g go -o /gen/out/python-petstore -p packageName=petstore_api # generates python client, outputs locally to ./out/python-petstore

Troubleshooting

If an error like this occurs, just execute the mvn clean install -U command:

org.apache.maven.lifecycle.LifecycleExecutionException: Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:2.19.1:test (default-test) on project openapi-json-schema-generator: A type incompatibility occurred while executing org.apache.maven.plugins:maven-surefire-plugin:2.19.1:test: java.lang.ExceptionInInitializerError cannot be cast to java.io.IOException

./run-in-docker.sh mvn clean install -U

Failed to execute goal org.fortasoft:gradle-maven-plugin:1.0.8:invoke (default) on project openapi-json-schema-generator-gradle-plugin-mvn-wrapper: org.gradle.tooling.BuildException: Could not execute build using Gradle distribution 'https://services.gradle.org/distributions/gradle-4.7-bin.zip'

Right now: no solution for this one :|

Run Docker in Vagrant

Prerequisite: install Vagrant and VirtualBox.

git clone https://github.com/openapitools/openapi-json-schema-generator.git
cd openapi-json-schema-generator
vagrant up
vagrant ssh
cd /vagrant
./run-in-docker.sh mvn package

1.7 - NPM

There is also an NPM package wrapper available for different platforms (e.g. Linux, Mac, Windows). (JVM is still required) Please see the project's README there for more information.

Install it globally to get the CLI available on the command line:

npm install @openapitools/openapi-json-schema-generator-cli -g
openapi-json-schema-generator-cli version

To use a specific version of "openapi-json-schema-generator-cli"

openapi-json-schema-generator-cli version-manager set 6.1.0

Or install it as dev-dependency:

npm install @openapitools/openapi-json-schema-generator-cli -D

2 - Getting Started

To generate a PHP client for petstore.yaml, please run the following

git clone https://github.com/openapitools/openapi-json-schema-generator
cd openapi-json-schema-generator
mvn clean package
java -jar modules/openapi-json-schema-generator-cli/target/openapi-json-schema-generator-cli.jar generate \
   -i https://raw.githubusercontent.com/openapitools/openapi-json-schema-generator/master/modules/openapi-json-schema-generator/src/test/resources/3_0/petstore.yaml \
   -g php \
   -o /var/tmp/php_api_client

(if you're on Windows, replace the last command with java -jar modules\openapi-json-schema-generator-cli\target\openapi-json-schema-generator-cli.jar generate -i https://raw.githubusercontent.com/openapitools/openapi-json-schema-generator/master/modules/openapi-json-schema-generator/src/test/resources/3_0/petstore.yaml -g php -o c:\temp\php_api_client)

You can also download the JAR (latest release) directly from maven.org

To get a list of general options available, please run java -jar modules/openapi-json-schema-generator-cli/target/openapi-json-schema-generator-cli.jar help generate

To get a list of PHP specified options (which can be passed to the generator with a config file via the -c option), please run java -jar modules/openapi-json-schema-generator-cli/target/openapi-json-schema-generator-cli.jar config-help -g php

3 - Usage

To generate a sample client library

You can build a client against the Petstore API as follows:

./bin/generate-samples.sh ./bin/configs/python.yaml

(On Windows, please install GIT Bash for Windows to run the command above)

This script will run the generator with this command:

java -jar modules/openapi-json-schema-generator-cli/target/openapi-json-schema-generator-cli.jar generate \
  -i https://raw.githubusercontent.com/openapitools/openapi-json-schema-generator/master/modules/openapi-json-schema-generator/src/test/resources/3_0/petstore.yaml \
  -g python \
  -t modules/openapi-json-schema-generator/src/main/resources/python \
  --additional-properties packageName=petstore_api \
  -o samples/openapi3/client/petstore/python

with a number of options. The python options are documented here.

You can also get the options with the help generate command (below only shows partial results):

NAME
        openapi-json-schema-generator-cli generate - Generate code with the specified
        generator.

SYNOPSIS
        openapi-json-schema-generator-cli generate
                [(-a <authorization> | --auth <authorization>)]
                [--api-name-suffix <api name suffix>] [--api-package <api package>]
                [--artifact-id <artifact id>] [--artifact-version <artifact version>]
                [(-c <configuration file> | --config <configuration file>)] [--dry-run]
                [(-e <templating engine> | --engine <templating engine>)]
                [--enable-post-process-file]
                [(-g <generator name> | --generator-name <generator name>)]
                [--generate-alias-as-model] [--git-host <git host>]
                [--git-repo-id <git repo id>] [--git-user-id <git user id>]
                [--global-property <global properties>...] [--group-id <group id>]
                [--http-user-agent <http user agent>]
                [(-i <spec file> | --input-spec <spec file>)]
                [--ignore-file-override <ignore file override location>]
                [--import-mappings <import mappings>...]
                [--instantiation-types <instantiation types>...]
                [--invoker-package <invoker package>]
                [--language-specific-primitives <language specific primitives>...]
                [--legacy-discriminator-behavior] [--library <library>]
                [--log-to-stderr] [--minimal-update]
                [--model-name-prefix <model name prefix>]
                [--model-name-suffix <model name suffix>]
                [--model-package <model package>]
                [(-o <output directory> | --output <output directory>)] [(-p <additional properties> | --additional-properties <additional properties>)...]
                [--package-name <package name>] [--release-note <release note>]
                [--remove-operation-id-prefix]
                [--reserved-words-mappings <reserved word mappings>...]
                [(-s | --skip-overwrite)] [--server-variables <server variables>...]
                [--skip-validate-spec] [--strict-spec <true/false strict behavior>]
                [(-t <template directory> | --template-dir <template directory>)]
                [--type-mappings <type mappings>...] [(-v | --verbose)]

OPTIONS
        -a <authorization>, --auth <authorization>
            adds authorization headers when fetching the OpenAPI definitions
            remotely. Pass in a URL-encoded string of name:header with a comma
            separating multiple values

...... (results omitted)

        -v, --verbose
            verbose mode

You can then use the auto-generated client. The README.md is a good starting point.

Other generators have samples too.

3.1 - Customization

Please refer to customization.md on how to customize the output (e.g. package name, version)

3.2 - Workflow Integration (Maven, Gradle, Github, CI/CD)

Please refer to integration.md on how to integrate OpenAPI generator with Maven, Gradle, Github and CI/CD.

3.3 - Online OpenAPI generator

Please refer to online.md on how to run and use the openapi-json-schema-generator-online - a web service for openapi-json-schema-generator.

3.4 - License information on Generated Code

The OpenAPI JSON Schema Generator project is intended as a benefit for users of the Open API Specification. The project itself has the License as specified. In addition, please understand the following points:

The templates included with this project are subject to the License.
Generated code is intentionally not subject to the parent project license

When code is generated from this project, it shall be considered AS IS and owned by the user of the software. There are no warranties--expressed or implied--for generated code. You can do what you wish with it, and once generated, the code is your responsibility and subject to the licensing terms that you deem appropriate.

6 - History of OpenAPI JSON Schema Generator

OpenAPI JSON Schema Generator is based on OpenAPI Generator v6.2.0. It focuses on JSON schema support and the output is designed to be 100% compliance with JSON Schema.

7 - License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Comments

[BUG] [Python] 6.1.x Import missing for models with string pattern
Bug Report Checklist

[x] Have you provided a full/minimal spec to reproduce the issue?

[x] Have you validated the input using an OpenAPI validator (example)?

[x] Have you tested with the latest master to confirm the issue still exists?

[x] Have you searched for related issues/PRs?

[x] What's the actual output vs expected output?

[ ] [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

After the last minor relase (6.1.0) the python sdk is broken when a component schema with a string pattern is provided as reference for a endpoint parameter. In this scenario, in the api files is a missing import for the openapi_types.

In practice, using the openapi spec yaml below, in the 6.0.1 version, even though the model/uuid_component.py file was created is not used, and the openapi_type in the api file is a string:

'openapi_types': { 'pattern_value': (str,), },

Hopwever, in the new release, 6.1.0, the openapi_type is now described as UuidComponent but there is no model import in the file:

'openapi_types': { 'pattern_value': (UuidComponent,), },

openapi-generator version

6.1.0

OpenAPI declaration file content or url

--- openapi: 3.0.3 info: title: Test pattern version: 0.0.0 servers: - url: localhost paths: /api/{pattern_value}: get: tags: - test1 operationId: test1 parameters: - name: pattern_value in: path required: true schema: $ref: '#/components/schemas/uuid_component' responses: "200": description: OK content: application/json: schema: type: string components: schemas: uuid_component: pattern: "/[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}/" type: string

Generation Details

Python Language without additional configurations.

Steps to reproduce

Generate openapi 6.1.0 spec - python

Related issues/PRs

Suggest a fix
invalid
opened by jtvmatos 12
[BUG] [Python-experimental] Certain types in nested component schemas are interpreted as DynamicSchema
Bug Report Checklist

[x] Have you provided a full/minimal spec to reproduce the issue?

[x] Have you validated the input using an OpenAPI validator (example)?

[ ] Have you tested with the latest master to confirm the issue still exists?

[x] Have you searched for related issues/PRs?

[x] What's the actual output vs expected output?

[ ] [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

I am unable to construct a python-experimental-generated object that includes both a nested component schema property and allOf. Certain types (integer, number, boolean) become impossible to construct, being interpreted as a DynamicSchema instead of the actual type.

openapi-generator version

6.0.0

OpenAPI declaration file content or url

openapi: 3.0.0 info: version: 1.0.0 title: BugReproduction paths: {} components: schemas: Dog: type: object additionalProperties: false allOf: - $ref: "#/components/schemas/Animal" properties: species: enum: ["canine"] age: $ref: "#/components/schemas/Age" Age: type: object additionalProperties: false properties: unit: type: string value: type: integer Cat: type: object additionalProperties: false allOf: - $ref: "#/components/schemas/Animal" properties: species: enum: ["feline"] favorite_milk: type: string Animal: type: object properties: species: type: string discriminator: propertyName: species mapping: canine: "#/components/schemas/Dog" feline: "#/components/schemas/Cat"

Generation Details

I've generated the schema above with both the standard python generator and python-experimental for side-by-side comparisons:

# Using the "standard" python generator, for comparison openapi-generator generate \ -i openapi_specs/main.yml \ -g python \ --additional-properties generateSourceCodeOnly=true \ --additional-properties packageName=pystandard # Using the python-experimental generator _JAVA_OPTIONS="--add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED" \ openapi-generator generate \ -i openapi_specs/main.yml \ -g python-experimental \ --additional-properties generateSourceCodeOnly=true \ --additional-properties packageName=pyexperimental

(Note: the _JAVA_OPTIONS are passed to avoid this error:)

: java.lang.reflect.InaccessibleObjectException: Unable to make field transient java.util.HashMap$Node[] java.util.HashMap.table accessible: module java.base does not "opens java.util" to unnamed module @2c1a7075

Steps to reproduce

Run the generator steps above with the schema above

Attempt to create an object (comment in/out the different imports to compare standard and experimental)

# from pystandard.model.age import Age # from pystandard.model.dog import Dog from pyexperimental.model.age import Age from pyexperimental.model.dog import Dog def test_dog(): Dog(species="canine", age=Age(unit="years", value=2))

The standard Dog can be created just fine, but the experimental Dog cannot be constructed:

pyexperimental.exceptions.ApiTypeError: Invalid type. Required value type is one of [Decimal, FileIO, NoneType, bool, bytes, frozendict, str, tuple] and passed type was DynamicSchema at ['args[0]']['age']['value']

I've changed the type of value to a few different simple types—string works fine, but integer/number/boolean all fail.

Related issues/PRs

None to my knowledge

Suggest a fix

Per @spacether:

Hmm this may be because Animal sees Age as an AnyTypeSchema but a Dog instance is a DynamicSchema instance but it should be let through because Age is a DictSchema.

For wider context of my real-world use case: I have an API endpoint with a polymorphic request body—it can accept oneOf several animals (to run with the reproduction example). I have several different animals (not just two), and while most have pretty distinct properties (as above—Dog and Cat are quite distinct from one another), a few of them happen to have the exact same set of fields (say... name and number_of_legs). I need to be able to disambiguate between two animals with identical properties, so I'm adding the species field as a discriminator. Each specific animal defines species as an enum-of-one field to ensure a client doesn't create something like Giraffe(species="canine").

In my real-world example there are additional, common, sometimes-optional properties that all Animals define, which is why I'm using allOf. Maybe the species property and discriminator mapping is not actually necessary in this case (since its hard-coded on each concrete animal schema), and I should just perform server-side switching using that field myself? I had assumed providing the discriminator block would yield some benefit in generated code. (Still pretty new to this tool in general so I don't know for sure, but all the polymorphism examples in the docs talk about using it.)
invalid
opened by mikeknep 11
[BUG] `skipFormModel` not detected by `python` generator defined under `additional-properties`
Bug Report Checklist

[x] Have you provided a full/minimal spec to reproduce the issue?

[x] Have you validated the input using an OpenAPI validator (example)?

[] Have you tested with the latest master to confirm the issue still exists?

[x] Have you searched for related issues/PRs?

[ ] What's the actual output vs expected output?

[ ] [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

Created issue requested by @spacether. The openapi-generator python does not detect skipFormModel. I need to set this property to false for my form models to be generated, I have no idea why this is true by default, but I assume it is an outdated model; however, it is in use by fastapi-users (authored/maintained by @frankie567, tagging because this is default of package).

From generator:

[main] INFO o.o.codegen.DefaultGenerator - Model Body_auth_database_login_user_auth_database_login_post not generated since it's marked as unused (due to form parameters) and `skipFormModel` (global property) set to true (default) [main] INFO o.o.codegen.DefaultGenerator - Model Body_auth_jwt_login_user_auth_jwt_login_post not generated since it's marked as unused (due to form parameters) and `skipFormModel` (global property) set to true (default)

Be assured that these models are in use, I fail to run the login functions because of the absence of these models.

openapi-generator version

latest stable, 6.2.0

OpenAPI declaration file content or url

My spec yaml, it has been validated.

Generation Details

openapi-generator generate --input-spec /home/can/Projects/SynDB/interface/syndb-pi/syndb_openapi.yaml --output /home/can/Projects/SynDB/interface/syndb-pi/syndb_openapi_gen_python --generator-name python --additional-properties=packageName=syndb_client,packageVersion=0.4.1,projectName=syndb_client,skipFormModel=false

Steps to reproduce

Run the command above with spec file from gist.
bug invalid
opened by caniko 7
[REQ] Run static checker on generated python code

Is your feature request related to a problem? Please describe.

More an opportunity than a problem. Static type analysis is getting more popular in python. This complements testing in helping reduce bugs in the generated code. Additionally it will help make sure that the generated code is typed in a way that helps consumers with their own static analysis.

Describe the solution you'd like

Now that the python-experimental branch doesn't' support python 2 it's possible to run mypy (static analysis) on the code as part of tox. This would require a number of fixes/changes to be applied to the generator to get it working

Describe alternatives you've considered

There are a number of other type checkers available for python but mypy seems the most common at this time
enhancement

opened by meadsteve 6
[BUG][python] unsanitized ! in property names
Bug Report Checklist

[x] Have you provided a full/minimal spec to reproduce the issue?

[x] Have you validated the input using an OpenAPI validator (example)? -> The example validator does not resolve the gitlab reference; the generator does though

[x] Have you tested with the latest master to confirm the issue still exists?

[x] Have you searched for related issues/PRs?

[x] What's the actual output vs expected output?

[ ] [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

Wrapping the official json schema for gitlab-ci into a swagger document to generate models produces code that raises syntax errors.

According to this validator, their schema is valid so the "!reference" property should be handled properly

openapi-generator version

6.2.0

OpenAPI declaration file content or url

swagger: "2.0" info: title: wrap paths: {} definitions: GitlabCI: $ref: "https://gitlab.com/gitlab-org/gitlab/-/raw/master/app/assets/javascripts/editor/schema/ci.json"

Generation Details

Copy the specification to wrapper.yml and use the npx call below

Steps to reproduce

npx @openapitools/openapi-generator-cli generate -i wrapper.yml -g python -o repro --global-property models ❯ python3 -c "import repro.openapi_client.model.gitlab_ci as ci" Traceback (most recent call last): File "<string>", line 1, in <module> File "/Users/dysp/workspace/testpython/repro/openapi_client/model/gitlab_ci.py", line 60 def !reference() -> typing.Type['Reference']: ^ SyntaxError: invalid syntax

Related issues/PRs

Suggest a fix

It looks like baseName here should be sanitized
duplicate
opened by DyspC 5
[python] Add overload for endpoint
Close #34

Not familiar with handlebar context, let me know if there are any useful variables could be used .

PR checklist

[x] Read the contribution guidelines.

[x] Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.

[x] Run the following to build the project and update samples:
./mvnw clean package ./bin/generate-samples.sh ./bin/utils/export_docs_generators.sh

Commit all changed files. This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master. These must match the expectations made by your contribution. You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/python*. For Windows users, please run the script in Git BASH.
opened by EltonChou 4

[BUG] python-experimental client fails to properly deserialize using discriminator

Bug Report Checklist

[X] Have you provided a full/minimal spec to reproduce the issue?
[X] Have you validated the input using an OpenAPI validator (example)?
[X] Have you tested with the latest master to confirm the issue still exists?
[X] Have you searched for related issues/PRs?
[X] What's the actual output vs expected output?
[ ] [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

The python-experimental client does not properly deserialize an object when the only difference between two models is the discriminator.

Note that this could be solved by making the type_id an enum, but our use case does not allow for this. When using a discriminator, this should be enough for the client to resolve the type.

openapi-generator version

verified in v6.1.0 and :latest (as of 9/21/22)

OpenAPI declaration file content or url

The following spec can be used to generated a client:

openapi: 3.0.0
x-stoplight:
  id: mjnw03vw4ju5m
info:
  title: discriminator-test
  version: '1.0'
servers:
  - url: 'http://localhost:3000'
paths:
  /operators:
    post:
      summary: ''
      operationId: post-operators
      responses:
        '200':
          description: OK
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Operator'
components:
  schemas:
    AdditionOperator:
      type: object
      title: AdditionOperator
      x-stoplight:
        id: qtffupdjxr76d
      description: ''
      additionalProperties: false
      properties:
        a:
          type: number
          format: double
        b:
          type: number
          format: double
        operator_id:
          type: string
          default: ADD
      required:
        - a
        - b
        - operator_id
    Operator:
      title: Operator
      x-stoplight:
        id: gz5qgm5j0vayg
      oneOf:
        - $ref: '#/components/schemas/AdditionOperator'
        - $ref: '#/components/schemas/SubtractionOperator'
      discriminator:
        propertyName: operator_id
        mapping:
          ADD: '#/components/schemas/AdditionOperator'
          SUB: '#/components/schemas/SubtractionOperator'
      description: ''
    SubtractionOperator:
      type: object
      title: SubtractionOperator
      x-stoplight:
        id: qtffupdjxr76d
      description: ''
      additionalProperties: false
      properties:
        a:
          type: number
          format: double
        b:
          type: number
          format: double
        operator_id:
          type: string
          default: SUB
      required:
        - a
        - b
        - operator_id

-->

Generation Details

I generated my client using the dockerized version of the cli. The following was executed in powershell (with the spec being in the 'reference' directory)

docker run --rm -v "${PWD}/:/output" -v "${PWD}/reference:/input" openapitools/openapi-generator-cli:latest generate `
   -g python-experimental `
   -i /input/discriminator-test.yaml `
   -o /output/disc-test `
   --additional-properties=packageName=disc_test_api `
   --additional-properties=packageVersion=0.0.1

Steps to reproduce

After installing the client into a virtual environment, the following python will reproduce the error:

from disc_test_api.model.operator import Operator

x = {
    'a': 1.0,
    'b': 2.0,
    'operator_id': 'ADD'
}

op = Operator(**x)
print(op)

The error and stack trace is:

C:\code\openapi-ticket\venv\Scripts\python.exe C:/code/openapi-ticket/main.py 
Traceback (most recent call last):
  File "C:\code\openapi-ticket\main.py", line 10, in <module>
    op = Operator(**x)
  File "C:\code\openapi-ticket\disc-test\disc_test_api\model\operator.py", line 72, in __new__
    return super().__new__(
  File "C:\code\openapi-ticket\disc-test\disc_test_api\schemas.py", line 513, in __new__
    __path_to_schemas = cls.__get_new_cls(__arg, __validation_metadata)
  File "C:\code\openapi-ticket\disc-test\disc_test_api\schemas.py", line 381, in __get_new_cls
    other_path_to_schemas = cls._validate_oapg(arg, validation_metadata=validation_metadata)
  File "C:\code\openapi-ticket\disc-test\disc_test_api\schemas.py", line 1993, in _validate_oapg
    other_path_to_schemas = cls.__get_oneof_class(
  File "C:\code\openapi-ticket\disc-test\disc_test_api\schemas.py", line 1902, in __get_oneof_class
    raise ApiValueError(
disc_test_api.exceptions.ApiValueError: Invalid inputs given to generate an instance of <class 'disc_test_api.model.operator.Operator'>. Multiple oneOf schemas [<class 'disc_test_api.model.addition_operator.AdditionOperator'>, <class 'disc_test_api.model.subtraction_operator.SubtractionOperator'>] matched the inputs, but a max of one is allowed.

Related issues/PRs

Suggest a fix

duplicate

opened by fbl100 4

[REQ] name endpoint fns/methods using spec case operationId
Is your feature request related to a problem? Please describe.

Some engineers prefer that endpoint methods/fns be named using the original operationId spec case Can this feature be added to python-experimental? @rm3l

Describe the solution you'd like

Using the original case is possible but awkward because operationIds can be any string, even invalid python variable names like:

" "

"123"

"A-B"

So to implement this, the api classes would:

be an instance of TypedDict going from operationId to endpoint fn OR

assign the operationId in the class __dict__

Whichever one best works with type hints would be chosen. To do this, api_client may have to be passed in to each endpoint call. Pseudocode would look like:

operation_id = "A-B" endpoint = FakeApi[operation_id] api_response = endpoint(query=params={}, body={})

Describe alternatives you've considered

Or we can keep the code as-is where operationId is converted to python snake case

Additional context

This was requested in: https://github.com/OpenAPITools/openapi-generator/issues/5214#issuecomment-1007271490 Similar issue: https://github.com/OpenAPITools/openapi-generator/issues/3813

Please vote for what you want!

If you want spec case used for operationId please upvote with thumbs up 👍

if want the code to keep using snake case for endpoint method names vote thumbs down 👎

enhancement
opened by spacether 3

[BUG][python] Generator generating reserved word ("from")

Bug Report Checklist

[x] Have you provided a full/minimal spec to reproduce the issue?
[x] Have you validated the input using an OpenAPI validator (example)?
[x] Have you tested with the latest master to confirm the issue still exists?
[x] Have you searched for related issues/PRs?
[x] What's the actual output vs expected output?

Description

I am attempting to use a spec that I have no control over (I cannot just change the spec). A "step" structure is implemented with from and to properties; however, when the structure is nested, the from keyword does not get escaped. This results in invalid Python code being produced.

Upon importing the models, I am instantly hit with a syntax error:

>>> import openapi_client.models
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/local/lib/python3.8/dist-packages/openapi_client/models/__init__.py", line 14, in <module>
    from openapi_client.model.my_response import MyResponse
  File "/usr/local/lib/python3.8/dist-packages/openapi_client/model/my_response.py", line 45
    def from() -> typing.Type['MyResponseData']:
        ^
SyntaxError: invalid syntax

The associated code looks like (shortened slightly for brevity):

class MyResponse(
    schemas.DictSchema
):
    """NOTE: This class is auto generated by OpenAPI Generator.
    Ref: https://openapi-generator.tech

    Do not edit the class manually.
    """


    class MetaOapg:
        required = {
            "from",
            "to",
        }
        
        class properties:
        
            @staticmethod
            def from() -> typing.Type['MyResponseData']:
                return MyResponseData
        
            @staticmethod
            def to() -> typing.Type['MyResponseData']:
                return MyResponseData
            __annotations__ = {
                "from": _from,
                "to": to,
            }
    
    to: 'MyResponseData'
    
    @typing.overload
    def __getitem__(self, name: typing_extensions.Literal["from"]) -> 'MyResponseData': ...
    
    @typing.overload
    def __getitem__(self, name: typing_extensions.Literal["to"]) -> 'MyResponseData': ...
    
    @typing.overload
    def __getitem__(self, name: str) -> schemas.UnsetAnyTypeSchema: ...
    
    def __getitem__(self, name: typing.Union[typing_extensions.Literal["from", "to", ], str]):
        # dict_instance[name] accessor
        return super().__getitem__(name)
    
    
    @typing.overload
    def get_item_oapg(self, name: typing_extensions.Literal["from"]) -> 'MyResponseData': ...
    
    @typing.overload
    def get_item_oapg(self, name: typing_extensions.Literal["to"]) -> 'MyResponseData': ...
    
    @typing.overload
    def get_item_oapg(self, name: str) -> typing.Union[schemas.UnsetAnyTypeSchema, schemas.Unset]: ...
    
    def get_item_oapg(self, name: typing.Union[typing_extensions.Literal["from", "to", ], str]):
        return super().get_item_oapg(name)
    

    def __new__(
        cls,
        *args: typing.Union[dict, frozendict.frozendict, ],
        to: 'MyResponseData',
        _configuration: typing.Optional[schemas.Configuration] = None,
        **kwargs: typing.Union[schemas.AnyTypeSchema, dict, frozendict.frozendict, str, date, datetime, uuid.UUID, int, float, decimal.Decimal, None, list, tuple, bytes],
    ) -> 'MyResponse':
        return super().__new__(
            cls,
            *args,
            to=to,
            _configuration=_configuration,
            **kwargs,
        )

I do not know what the entirety of this code should look like, but I do know that the specific code producing the syntax error should at least look like this:

            @staticmethod
            def _from() -> typing.Type['MyResponseData']:
                return MyResponseData

openapi-json-schema-generator version

master branch; this is not a regression as the issue was reported here (and it is still an issue): https://github.com/OpenAPITools/openapi-generator/issues/7119

OpenAPI declaration file content or url

openapi: "3.0.0"
info:
  title: Sample
  version: "1.0.0"
paths:
  /test_one:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/my_response"
components:
  schemas:
    my_response:
      type: object
      properties:
        from:
          $ref: "#/components/schemas/my_response_data"
        to:
          $ref: "#/components/schemas/my_response_data"
      required:
        - from
        - to
    my_response_data:
      type: object
      properties:
        data:
          type: string
        id:
          type: integer

Generation Details

java -jar modules/openapi-json-schema-generator-cli/target/openapi-json-schema-generator-cli.jar generate \
    -i /TEST.yaml \
    -g python \
    -t modules/openapi-json-schema-generator/src/main/resources/python \
    -o TEST

Steps to reproduce

Built a Docker image from the following Dockerfile:

FROM maven:3.6.3-jdk-11-openj9

WORKDIR /

RUN apt update && apt install -y git curl unzip python3 python3-pip

RUN curl -L https://github.com/OpenAPITools/openapi-json-schema-generator/archive/refs/heads/master.zip -o master.zip \
    && unzip master.zip

WORKDIR /openapi-json-schema-generator-master

RUN mvn clean install

Then built and ran with:

docker build -t openapi-test -f Dockerfile.openapi .
docker run -it --rm openapi-test bash

Then from within docker

java -jar modules/openapi-json-schema-generator-cli/target/openapi-json-schema-generator-cli.jar generate \
    -i /TEST.yaml \
    -g python \
    -t modules/openapi-json-schema-generator/src/main/resources/python \
    -o TEST

And lastly, tried using the generated code:

cd TEST
python3 -m pip install .
python3 -c "import openapi_client.models"

HOWEVER THIS SPEC WORKS (no nesting)

openapi: "3.0.0"
info:
  title: Sample
  version: "1.0.0"
paths:
  /test_one:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/my_response"
components:
  schemas:
    my_response:
      type: object
      properties:
        from:
          type: string
        to:
          type: string
      required:
        - from
        - to

Related issues/PRs

https://github.com/OpenAPITools/openapi-generator/issues/7119

Suggest a fix

I am not sure how to fix this, but it seems like the escapeReservedWord function is not being called properly?

Edits

fixed some code formatting
fixed typo

bug

opened by Lnk2past 3

[BUG] [Python] Attribute error when using auth header
Fix #19

Use HTTPHeaderDict() instead of dict.

For Python client generation @spacether

PR checklist

[x] Read the contribution guidelines.

[x] Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.

[x] Run the following to build the project and update samples:
./mvnw clean package ./bin/generate-samples.sh ./bin/utils/export_docs_generators.sh

Commit all changed files. This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master. These must match the expectations made by your contribution. You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/python*. For Windows users, please run the script in Git BASH.
opened by totothekiller 3
[BUG] Regex patterns without trailing slashes break Python client generation
Bug Report Checklist

[x] Have you provided a full/minimal spec to reproduce the issue?

[x] Have you validated the input using an OpenAPI validator (example)?

[x] Have you tested with the latest master to confirm the issue still exists?

[x] Have you searched for related issues/PRs?

[x] What's the actual output vs expected output?

[ ] [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

When trying to generate a Python client SDK for a simple openAPI spec with an id with a given regex pattern, the generation fails with error Caused by: com.github.curiousoddman.rgxgen.parsing.dflt.RgxGenParseException: Unbalanced '{' - missing '}' at 'F0-9]{12' and (partial) stack trace

at com.github.curiousoddman.rgxgen.parsing.dflt.DefaultTreeBuilder.handleRepeatInCurvyBraces (DefaultTreeBuilder.java:479) at com.github.curiousoddman.rgxgen.parsing.dflt.DefaultTreeBuilder.handleRepeat (DefaultTreeBuilder.java:503) at com.github.curiousoddman.rgxgen.parsing.dflt.DefaultTreeBuilder.handleRepeatCharacter (DefaultTreeBuilder.java:314) at com.github.curiousoddman.rgxgen.parsing.dflt.DefaultTreeBuilder.parseGroup (DefaultTreeBuilder.java:249) at com.github.curiousoddman.rgxgen.parsing.dflt.DefaultTreeBuilder.build (DefaultTreeBuilder.java:664) at com.github.curiousoddman.rgxgen.parsing.dflt.DefaultTreeBuilder.get (DefaultTreeBuilder.java:673) at com.github.curiousoddman.rgxgen.RgxGen.<init> (RgxGen.java:71) at com.github.curiousoddman.rgxgen.RgxGen.<init> (RgxGen.java:62) at org.openapitools.codegen.languages.PythonClientCodegen.toExampleValueRecursive (PythonClientCodegen.java:1200) at org.openapitools.codegen.languages.PythonClientCodegen.toExampleValueRecursive (PythonClientCodegen.java:1128) at org.openapitools.codegen.languages.PythonClientCodegen.toExampleValue (PythonClientCodegen.java:1023) at org.openapitools.codegen.languages.PythonClientCodegen.setParameterExampleValue (PythonClientCodegen.java:1434)

This is not specific to the regex expression in my example and should happen with any regex that does not have ah extra char at the end that can be stripped without compromising the check that should be done.

openapi-generator version

6.0.0

OpenAPI declaration file content or url

--- openapi: 3.0.3 info: title: Test version: 1.0.0-SNAPSHOT paths: /test: get: tags: - Test Resource parameters: - name: uuid in: query schema: $ref: '#/components/schemas/UUID' responses: "200": description: OK components: schemas: UUID: format: uuid pattern: "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}" type: string

Generation Details

Regular maven plugin generation with <generatorName>python</generatorName>

Steps to reproduce

place the open api spec above somwhere the maven plugin can get it

run mvn clean package in a pom.xml file with <inputSpec> linking to the file created in 1

check the error that should be Unbalanced '{' - missing '}' at 'F0-9]{12'

Related issues/PRs

Suggest a fix

The problem seems to be with the REGEX in https://github.com/OpenAPITools/openapi-generator/blame/0c825ad3019e76b9d85e9883ef960a4643277c54/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/PythonClientCodegen.java#L1179 where it should only strip of leading /, trailing / or trailing /i.

However, this REGEX is placing ANY final char into the second group, which means that in the case represented in this issue the main group will be [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12, because the final } is being captured as part of group 2.

Examples here: https://regex101.com/r/4YqK9h/1

I think what we want is something like ^/?(.+?)/?(i?)$ as shown in https://regex101.com/r/RAxPJU/1, where we really only capture trailing / or /i, not any last character that might be in the pattern.
bug
opened by antssilva96 3
[Announcement] Repo has been relocated

On Oct 2nd 2022, Justin (@spacether), who's been leading this project openapi-json-schema-generator with the goal to make the output 100% compliant with JSON schema as part of the OpenAPI 3.1 specification with a focus on complex cases (top-down approach), has decided to run this project in another organization account openapi-json-schema-tools instead so that he can fine tune the pace of the projects to align with different goals and requirements. Please follow openapi-json-schema-tools/openapi-json-schema-generator if you would like to take advantage of the latest works (enhancements, bug fixes) by Justin.

@jmini @RadaofTheLight @Shakey1977 @bbezanson @dmholtz @bew @isabella232 @totothekiller

opened by spacether 0