You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Dec 25, 2024. It is now read-only.
@@ -23,39 +23,43 @@ You can join us here: https://discord.gg/mHB8WEQuYQ
23
23
24
24
## Reasons To Use the Python Generator
25
25
26
-
-[Autogenerated thorough testing of json schema keyword features in models and endpoints](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/tree/master/samples/client/3_0_3_unit_test/python/test) which come from the [json schema test suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite)
27
-
-[Tests are passing in CI](https://app.circleci.com/pipelines/github/openapi-json-schema-tools/openapi-json-schema-generator?branch=master)
28
-
-[Test endpoints are tagged by the relevant keyword like type/format/allOf 25+ keywords and counting](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/tree/master/samples/client/3_0_3_unit_test/python/docs/apis/tags)
26
+
- Type hints on
27
+
- schema payload inputs in SomeSchema.validate 
28
+
- Note: to make input dictionaries TypedDicts like the Money.validate example, set additionalProperties to false in the schema in your openapi document
29
+
- schema keyword argument inputs in `SomeSchemaDict.__new__`
30
+
- accessing properties in object instances so some_val in some_val = some_inst.someKey will have the correct type hint 
31
+
- accessing array items in array instances so some_val in some_val = array_inst[0] will have the correct type hint
32
+
- endpoint inputs + responses
29
33
- Run time type checking and validation checking when:
30
34
- instantiating models
31
35
- sending to endpoints
32
36
- receiving from endpoints
33
-
- Type hints on
34
-
- all model inputs in `__new__`
35
-
- accessing properties in object instances so some_val in some_val = some_inst['someKey'] will have the correct type hint
36
-
- accessing array items in array instances so some_val in some_val = array_inst[0] will have the correct type hint
37
-
- endpoint inputs + responses
37
+
- Note: if needed, validation of json schema keywords can be deactivated via a SchemaConfiguration class
38
+
-[mypy](samples/client/petstore/python/test_python.sh) runs on sample petstore client and passes
39
+
- passing mypy tests means that this generator could be ported into compiled languages lik java/kotlin/golang
40
+
-[Autogenerated thorough testing of json schema keyword features in models and endpoints](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/tree/master/samples/client/3_0_3_unit_test/python/test) which come from the [json schema test suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite)
41
+
-[Tests are passing in CI](https://app.circleci.com/pipelines/github/openapi-json-schema-tools/openapi-json-schema-generator?branch=master)
42
+
-[Test endpoints are tagged by the relevant keyword like type/format/allOf 25+ keywords and counting](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/tree/master/samples/client/3_0_3_unit_test/python/docs/apis/tags)
38
43
- Code re-use built in from the ground up
39
44
- components/schemas/headers etc are generated as separate classes and imported when used via $ref
40
45
- Openapi spec inline schemas supported at any depth in any location
41
46
- Format support for: int32, int64, float, double, binary, date, datetime, uuid
42
47
- Invalid (in python) property names supported like `from`, `1var`, `hi-there` etc in
43
48
- schema property names
44
49
- endpoint parameter names
45
-
- If needed, validation of some json schema keywords can be deactivated via a configuration class
46
50
- Payload values are not coerced when validated, so a datetime value can pass other validations that describe the payload only as type string
47
-
- String transmission of numbers supported with type: string, format: number, value can be accessed as a Decimal with inst.as_decimal_
51
+
- types are generated for enums of type string/integer/boolean using typing.Literal
52
+
- String transmission of numbers supported with type: string, format: number, value can be accessed as a Decimal with schemas.as_decimal(inst)
48
53
- Multiple content types supported for request and response bodies
49
54
- Endpoint response always also includes the urllib3.HTTPResponse
50
55
- Endpoint response deserialization can be skipped with the skip_deserialization argument
51
-
- Validated payload instances subclass all validated schemas so no need to run validate twice, just use isinstance(some_inst, SomeSchemaClass)
52
56
53
57
And many more!
54
-
-[Docs for the python generator](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/blob/master/docs/generators/python.md)
55
-
-[Openapi v3.0.3 general petstore spec, general features](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/blob/master/src/test/resources/3_0/python/petstore_customized.yaml)
-[Openapi json schema v3.0.3 unit test spec](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/blob/master/src/test/resources/3_0/unit_test_spec/3_0_3_unit_test_spec.yaml)
-[3.3 - License Information on Generated Code](#34---license-information-on-generated-code)
79
-
-[4 - Companies/Projects using OpenAPI JSON Schema Generator](#4---companiesprojects-using-openapi-json-schema-generator)
80
-
-[5 - About Us](#5---about-us)
81
-
-[5.1 - History of OpenAPI JSON Schema Generator](#51---history-of-openapi-json-schema-generator)
82
-
-[6 - License](#6---license)
83
-
84
-
## [1 - Installation](#table-of-contents)
85
-
86
-
### [1.1 - Compatibility](#table-of-contents)
74
+
-[Installation](#installation)
75
+
-[Compatibility](#compatibility)
76
+
-[Build Projects](#build-projects)
77
+
-[Docker](#docker)
78
+
-[Getting Started](#getting-started)
79
+
-[Usage](#usage)
80
+
-[Customization](#customization)
81
+
-[Workflow Integration](#workflow-integration)
82
+
-[License Information](#license-information)
83
+
-[Companies/Projects using OpenAPI JSON Schema Generator](#companiesprojects-using-openapi-json-schema-generator)
84
+
-[About Us](#about-us)
85
+
-[History of OpenAPI JSON Schema Generator](#history-of-openapi-json-schema-generator)
86
+
-[License](#license)
87
+
88
+
## Installation
89
+
90
+
### Compatibility
87
91
88
92
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:
@@ -100,7 +105,7 @@ The OpenAPI Specification has undergone 3 revisions since initial creation in 20
100
105
| 1.0.0 | 3.0.0 - 3.0.3 |
101
106
102
107
103
-
### [1.2 - Build Projects](#table-of-contents)
108
+
### Build Projects
104
109
105
110
To build from source, you need the following installed and available in your `$PATH:`
106
111
@@ -119,7 +124,7 @@ The default build contains minimal static analysis (via CheckStyle). To run your
119
124
mvn -Pstatic-analysis clean install
120
125
```
121
126
122
-
### [1.3 - Docker](#table-of-contents)
127
+
### Docker
123
128
124
129
#### Public Pre-built Docker images
125
130
@@ -182,7 +187,7 @@ If an error like this occurs, just execute the **mvn clean install -U** command:
182
187
Right now: no solution for this one :|
183
188
184
189
<!-- /RELEASE_VERSION -->
185
-
## [2 - Getting Started](#table-of-contents)
190
+
## Getting Started
186
191
187
192
To generate a python client for [petstore.yaml](https://raw.githubusercontent.com/openapi-json-schema-tools/openapi-json-schema-generator/master/src/test/resources/3_0/petstore.yaml), please run the following
188
193
```sh
@@ -204,7 +209,7 @@ To get a list of **general** options available, please run `java -jar target/ope
204
209
205
210
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 target/openapi-json-schema-generator-cli.jar config-help -g php`
206
211
207
-
## [3 - Usage](#table-of-contents)
212
+
## Usage
208
213
209
214
### To generate a sample client library
210
215
You can build a client against the [Petstore API](https://raw.githubusercontent.com/openapijsonschematools/openapi-json-schema-generator/master/src/test/resources/3_0/petstore.yaml) as follows:
@@ -283,17 +288,17 @@ OPTIONS
283
288
284
289
You can then use the auto-generated client. The README.md is a good starting point.
285
290
286
-
Other generators have [samples](https://github.com/OpenAPITools/openapi-json-schema-generator/tree/master/samples) too.
291
+
Other generators have [samples](samples) too.
287
292
288
-
### [3.1 - Customization](#table-of-contents)
293
+
### Customization
289
294
290
295
Please refer to [customization.md](docs/customization.md) on how to customize the output (e.g. package name, version)
Please refer to [integration.md](docs/integration.md) on how to integrate OpenAPI generator with Maven, Gradle, Github and CI/CD.
295
300
296
-
### [3.3 - License information on Generated Code](#table-of-contents)
301
+
### License Information
297
302
298
303
The OpenAPI JSON Schema Generator project is intended as a benefit for users of the Open API Specification. The project itself has the [License](#license) as specified. In addition, please understand the following points:
299
304
@@ -302,13 +307,15 @@ The OpenAPI JSON Schema Generator project is intended as a benefit for users of
302
307
303
308
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.
304
309
305
-
## [4 - Companies/Projects using OpenAPI JSON Schema Generator](#table-of-contents)
310
+
## Companies/Projects using OpenAPI JSON Schema Generator
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.
310
317
311
-
### [5.1 - History of OpenAPI JSON Schema Generator](#table-of-contents)
318
+
### History of OpenAPI JSON Schema Generator
312
319
313
320
OpenAPI JSON Schema Generator is based on OpenAPI Generator v6.2.0.
314
321
The project was created here because the openapi-generator core team required the removal of the python generator
@@ -331,10 +338,10 @@ Below is a timeline of those events and some of their reasons:
331
338
- The fact that it is more fully passing json schema tests (including the feature keywords oneOf/anyOf/allOf/additionalProperties) does not warrant keeping it in the repo
332
339
- The openapi-generator core team refused to consider the option of keeping the python generator as another generator option in their repo, and building another python generator that looks more conventional and making that generator primary
| helpTxt | Generates a Python client library<br /><br />Features in this generator:<br />- type hints on endpoints and model creation<br />- model parameter names use the spec defined keys and cases<br />- robust composition (oneOf/anyOf/allOf/not) where payload data is stored in one instance only<br />- endpoint parameter names use the spec defined keys and cases<br />- inline schemas are supported at any location including composition<br />- multiple content types supported in request body and response bodies<br />- run time type checking<br />- Sending/receiving decimals as strings supported with type:string format: number -> DecimalSchema<br />- Sending/receiving uuids as strings supported with type:string format: uuid -> UUIDSchema<br />- quicker load time for python modules (a single endpoint can be imported and used without loading others)<br />- all instances of schemas dynamically inherit from all matching schemas so one can use isinstance to check if validation passed<br />- composed schemas with type constraints supported (type:object + oneOf/anyOf/allOf)<br />- schemas are not coerced/cast. For example string + date are both stored as string, and there is a date accessor<br /> - Exceptions: int/float is stored as Decimal, When receiving data from headers it will start as str and may need to be cast for example to int | |
15
+
| helpTxt | Generates a Python client library<br /><br />Features in this generator:<br />- type hints on endpoints and model creation<br />- model parameter names use the spec defined keys and cases<br />- robust composition (oneOf/anyOf/allOf/not) where payload data is stored in one instance only<br />- endpoint parameter names use the spec defined keys and cases<br />- inline schemas are supported at any location including composition<br />- multiple content types supported in request body and response bodies<br />- run time type checking + json schema validation<br />- json schema keyword validation may be selectively disabled with SchemaConfiguration<br />- enums of type string/integer/boolean typed using typing.Literal<br />- mypy static type checking run on generated sample<br />- Sending/receiving decimals as strings supported with type:string format: number -> DecimalSchema<br />- Sending/receiving uuids as strings supported with type:string format: uuid -> UUIDSchema<br />- quicker load time for python modules (a single endpoint can be imported and used without loading others)<br />- composed schemas with type constraints supported (type:object + oneOf/anyOf/allOf)<br />- schemas are not coerced/cast. For example string + date are both stored as string, and there is a date accessor | |
16
16
17
17
## CONFIG OPTIONS
18
18
These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
0 commit comments