Should generate `Aliases?: null | string[]` instead of `Aliases?: string[]`

[loynoir]

Description

Should generate Aliases?: null | string[] instead of Aliases?: string[]

Name	Version
openapi-typescript	5.4.1
Node.js	v18.15.0
OS + version	ArchLinux

Story
Docker is using swagger 2.0 https://github.com/moby/moby/blob/master/docs/api/v1.42.yaml

When I use version 6.2.1, I got Swagger 2.0 and older no longer supported. Please use v5..

But when I use version 5.4.1, found type not very correct.

Not sure it is a bug in openapi-typescript, or a bug in docker api spec.

Reproduction

https://github.com/moby/moby/blob/a343ed13e556ec97a26bd5fc34b069a64f86f16b/docs/api/v1.42.yaml#L2406-L2427

  EndpointSettings:
    description: "Configuration for a network endpoint."
    type: "object"
    properties:
      # Configurations
      IPAMConfig:
        $ref: "#/definitions/EndpointIPAMConfig"
      Links:
        type: "array"
        items:
          type: "string"
        example:
          - "container_1"
          - "container_2"
      Aliases:
        type: "array"
        items:
          type: "string"
        example:
          - "server_x"
          - "server_y"

Actual result

$ npm add -D openapi-typescript@5.4.1 
$ npm exec -- openapi-typescript /path/to/docker/api/v1.42.yaml --output v1.42.d.ts

Partial output

  EndpointSettings: {
    IPAMConfig?: definitions["EndpointIPAMConfig"];
    /**
     * @example [
     *   "container_1",
     *   "container_2"
     * ]
     */
    Links?: string[];
    /**
     * @example [
     *   "server_x",
     *   "server_y"
     * ]
     */
    Aliases?: string[];

But in runtime, .Aliases maybe null.

      const a: { Aliases?: string[] } = {
        // @ts-expect-error: not assignable
        Aliases: null,
      }
      void a

So, the type is wrong.

Expected result

    Aliases?: null | string[];

Checklist

• I’m willing to open a PR (see CONTRIBUTING.md)

[mitchell-merry]

As far as I can tell, swagger 2.x does not have proper support for null arguments (over undefined). See stackoverflow comment. I'm not sure what we can do here, in terms of changing the library to suit this problem. @drwpow probably has more context on that.

As for what you can do right now, use the formatter API, see here: https://github.com/drwpow/openapi-typescript/tree/5.x#custom-formatter. This should let you override what openapi-typescript does for specific cases - in this cases, the behavior for non-required fields. Let me know if that helps.

[drwpow]

Yeah the handling of null properties was ambiguous in many cases like @mitchell-merry said. This library does have a 5.x branch (as well as all previous versions) meant for bugfixes. I’d be open to possibly fixing this, however, it’s not clear to me that this is a “bug” because this is the first time it’s been reported. I’m worried that making this breaking change could break the other users still on 5.x.

I’d agree with Mitchell’s suggestion of using the formatter API for now. But again, if there is a clear bugfix that wouldn’t be a breaking change to people, we can push patch versions to 5.x if needed.

[loynoir]

@mitchell-merry

As far as I can tell, swagger 2.x does not have proper support for null arguments (over undefined).

@drwpow

I’d be open to possibly fixing this, however, it’s not clear to me that this is a “bug” because this is the first time it’s been reported.

Although can workaround on this, I gonna to open a feature request on side of docker to migrate from swagger 2.0 to openapi 3 spec, if possible.

But before that, I have a few questions.

• Does openapi 3 spec have better definition support for null?

• Is openapi 3 spec still considering as new thing, or considering as production ready?

• How large is the difference between openapi 3 spec and swagger 2.0?

• Is there a migration guide or migration tool for golang, the language docker written in?

[mitchell-merry]

It's production ready. In 3.0.x there's a nullable property, and in 3.1.x I think that was replaced with the following:

oneOf:
- (your type)
- 'null'

It's a significant difference, especially in the tooling surrounding it, but I think there are many features in 3.1 that are significantly better than 2.x. Personally, I'm trying to get our team's swagger file upgraded as soon as I can.

We won't have any context on the Docker spec or golang that you don't have, though.

[mitchell-merry]

Closing this as it seems to be addressed.