OpenAPITools / OpenAPITools/openapi-generator
[BUG][MARKDOWN] Some OpenAPI attributes are incorrectly represented as "null" strings (rather than literal `null`s)
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
Bug Report Checklist
- Have you provided a full/minimal spec to reproduce the issue?
- Have you validated the input using an OpenAPI validator (example)?
- Have you tested with the latest master to confirm the issue still exists?
- 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
Some optional OpenAPI fields are incorrectly represented within Mustache templates as the string value "null", rather than as the null literal. This means that checks that should be "falsy" really aren't.
My specific use case is examples. Most (but not all) fields in my OpenAPI spec provide examples. If they do, I want to render an "Example" section. If they don't, I want to render nothing. This bug prevents that.
openapi-generator version
6.0.1
OpenAPI declaration file content or URL
This minimal spec can be used to reproduce the bug:
openapi: 3.0.3
info:
title: Bug Reproduction
version: 0.0.0
paths: {}
components:
schemas:
BugReproduction:
properties:
field:
type: number
Note that the field property on this BugReproduction schema lacks example, pattern, and minItems attributes. This fact is important.
Generation Details
The command I used to reproduce this bug is as follows...
openapi-generator generate -i bug.yaml -o tmp -g markdown -t ./templates
Steps to reproduce
- Create a file in the
templatesdirectory namedmodel.mustache. Add the following contents:
Example Start
{{#models}}
{{#model}}
{{#vars}}
{{{name}}} {{! Should output "field" }}
{{{minItems}}} {{! Should output nothing }}
{{{example}}} {{! Should output nothing }}
{{{pattern}}} {{! Should output nothing }}
{{/vars}}
{{/model}}
{{/models}}
Example End
- Run the aforementioned command, with
bug.yamlcontaining the example YAML posted above. - You will see output that looks like the following:
Example Start
field
null
Example End
Some fields in the CodegenProperty provided to the template have null values, while others have "null" values.
The following fields within the above CodegenProperty (omitted for brevity) incorrectly have "null" string values:
complexTypedescriptiondataFormatminmaxdefaultValuecontainerTypetitleunescapedDescriptionpatternexamplediscriminatorValueenumNamexmlPrefixxmlNamexmlNamespace
The following fields within the above CodegenProperty correctly have null literal values:
maxLengthminLength_enumallowableValuesitemsadditionalPropertiesmostInnerItemsmaxItemsminItemsmaxPropertiesminPropertiesmultipleOfcomposedSchemas
Related issues/PRs
Couldn't find anything.
Suggest a fix
Don't know yet, but I can take a closer look later.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the issue with the supplied bug.yaml, the markdown generator command, and templates/model.mustache, then inspect how CodegenProperty values reach Mustache templates. Done means absent optional attributes render as literal null values rather than the string "null", while present values continue to render correctly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, markdown
- Domain
- documentation, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100