When referencing another schema, and making it nullable it breaks the export

system · June 4, 2025, 3:03pm

Output while using “Reference other schemas”

    "description": "",
    "anyOf": [
        {
            "description": "",
            "$ref": "#/definitions/407005"
        },
        {
            "type": "null"
        }
    ]
}```

Instead of adding a nullable attribute with the ref to the property.

This creates issue's with code-generators for the open-api-spec.

system · June 4, 2025, 3:40pm

Thank you for the feedback. We’ll look into this issue.

thisevans · June 5, 2025, 6:25am

Hi, did you export spec in OpenAPI 3.0 format?

system · June 5, 2025, 7:07am

Evans Yes, I did

system · June 5, 2025, 7:54am

Evans I have also researched this a bit more and I have to admit I was a bit in the wrong as well:

when using $refs, we can’t really use nullable (see: OpenAPI 3.0: How to make objects nullable that use oneOf, allOf, or anyOf ~ Dan Ott for example)
The real issue is the following:
The output generated from ApiDog is the following (a bit stripped, because of company specific):

        foo:
          description: Foo description
          anyOf:
            - description: Foo description
              $ref: '#/definitions/407005'
            - type: 'null'
          $ref: '#/components/schemas/Foo'

While the correct syntax that works without any issue’s should be:

        unitProfile:
          description: Foo description
          anyOf:
            - $ref: '#/components/schemas/Foo'
            - type: 'null'

system · June 5, 2025, 7:56am

It seems like it doesn’t link the correct definition anymore, combined with the description in the anyOf definition of the ref creates an invalid yaml, the description in the anyOf isn’t a real problem (more that the spec disallows it, but generating still works).
But the wrong definition reference gives issue’s ofcourse.

thisevans · June 5, 2025, 12:44pm

Johannes Thanks for your feedback, we’ll look into it.