Created by: sebastien-rosset
Background
As per OAS specification:
- Undeclared properties should be allowed when the
additionalProperties
keyword is not specified, whenadditionalProperties: true
or whenadditionalProperties: {}
. TheadditionalProperties
keyword can also be used to specify a schema for the undeclared properties. - A composed schema may include the
additionalProperties
keyword, both as a sibling of allOf/oneOf/anyOf, and in the child schemas. - The value of undeclared properties may be the null value.
Changes
- Add
disallowAdditionalPropertiesIfNotPresent
CLI option to control the interpretation of theadditionalProperties
keyword. See below for more details. - Change the interpretation of the
additionalProperties
keyword to comply with the OAS 2.0 and 3.x specifications.- Specifically, the following behavior changes have been made and are necessary to comply with the OAS spec:
- When the
additionalProperties
keyword is not present in the OAS document, that should be interpreted as ifadditionalProperties
had been set totrue
. - The additional properties should be nullable, i.e. the null value should be allowed.
- When the
- Some people may have built their OAS documents with the understanding that by default, additional properties are not allowed, because they incorrectly assumed the OpenAPITools implementation was correct. To retain the legacy behavior you can set the
disallowAdditionalPropertiesIfNotPresent
CLI option totrue
, which is the default for now. - Limitation: due to issue swagger-parser #1369, achieving OAS compliance is not possible when the input document uses the OAS 2.0 schema. For OAS 2.0 documents, the legacy behavior should be used by setting the
disallowAdditionalPropertiesIfNotPresent
CLI option totrue
.
- Specifically, the following behavior changes have been made and are necessary to comply with the OAS spec:
- By default the CLI option is set to
true
(i.e. non-compliant behavior, as originally implemented). Initially I wanted to change the default value tofalse
for all code generators, but it's too much work. For now I am only enabling the compliant mode forpython-experimental
. - Codegen and mustache templates were not properly processing composed schemas that have the
additionalProperties
keyword set. The issue is specifically resolved for python-experimental. - codegen: add equals and hashCode methods for SemVer class.
- python-experimental: add unit test to validate a composed schema with additionalProperties and other use cases related to the
additionalProperties
keyword. - python-experimental: correctly handle the OAS
nullable
keyword. When a schema is nullable, the client should accept thenull
value in the input data. - python-experimental: correctly handle
additionalProperties
which is referencing a schema with a$ref
. Generate imports - python-experimental: correctly generate the data type when
additionalProperties
references a schema - Add code comments in codegen.
Note: breaking changes are introduced in this PR, but they are necessary to be compliant with the OAS specification.
For example:
Dog:
allOf:
- $ref: '#/components/schemas/Animal'
- type: object
properties:
breed:
type: string
In the above example, the additionalProperties
keyword is not specified, which means by default undeclared properties should be allowed. This equivalent to:
Dog:
additionalProperties: true
allOf:
- $ref: '#/components/schemas/Animal'
- type: object
properties:
breed:
type: string
Related Issues and future work
While working on this PR, the following related issues have been identified:
- swagger-parser #1378 swagger-v2-converter incorrectly converts 2.0 schemas that do not have the 'type' keyword
- swagger-parser #1369: additionalProperties not set correctly if omitted
- Once the above issues have been fixed, some of the code in this PR can be disabled. Specifically it will no longer be necessary to differentiate between OAS 2.0 docs and OAS 3.0 docs.
- swagger-parser #1374: when a OAS 2.0 doc is converted, it would be helpful to retain the "2.0" version in a vendor extension, that would make it possible to know the original OAS doc was 2.0, not 3.x. That can help to drive some of the processing logic.
- Support for composed schemas that use the
additionalProperties
keyword is limited to python-experimental for now. Significant changes may have to be done in other languages. For example, in the Java clients, single inheritance is used, that causes a conflict between inheriting theallOf
parent and theHashMap
parent. - Some of the names in samples OAS documents should be changed to better reflect the intent and behavior. See discussion in this PR for more details.
- Issue #6400
PR checklist
-
Read the contribution guidelines. -
If contributing template-only or documentation-only changes which will change sample output, build the project before. -
Run the shell script(s) under ./bin/
(or Windows batch scripts under.\bin\windows
) to update Petstore samples related to your fix. This is important, as CI jobs will verify all generator outputs of your HEAD commit, and these must match the expectations made by your contribution. You only need to run./bin/{LANG}-petstore.sh
,./bin/openapi3/{LANG}-petstore.sh
if updating the code or mustache templates for a language ({LANG}
) (e.g. php, ruby, python, etc). -
File the PR against the correct branch: master
,4.3.x
,5.0.x
. Default:master
. -
Copy the technical committee to review the pull request if your PR is targeting a particular programming language.