OpenAPITools / OpenAPITools/openapi-generator

[BUG][MARKDOWN] Some OpenAPI attributes are incorrectly represented as "null" strings (rather than literal `null`s)

Open
#12,807 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Issue: Bug
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
  1. Create a file in the templates directory named model.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
  1. Run the aforementioned command, with bug.yaml containing the example YAML posted above.
  2. 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:

  • complexType
  • description
  • dataFormat
  • min
  • max
  • defaultValue
  • containerType
  • title
  • unescapedDescription
  • pattern
  • example
  • discriminatorValue
  • enumName
  • xmlPrefix
  • xmlName
  • xmlNamespace

The following fields within the above CodegenProperty correctly have null literal values:

  • maxLength
  • minLength
  • _enum
  • allowableValues
  • items
  • additionalProperties
  • mostInnerItems
  • maxItems
  • minItems
  • maxProperties
  • minProperties
  • multipleOf
  • composedSchemas
Related issues/PRs

Couldn't find anything.

Suggest a fix

Don't know yet, but I can take a closer look later.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.