Nullable fields produce '"nullable": true' in a oneOf

[OxonianCambion]

I've been using your serverless-openapi-documenter and I think the root cause is in here.

When converting something of the form:

"foo": {
  "title": "foo",
  "type": [
    "string",
    "null"
  ]
}

the converted output is

"foo": {
  "title": "foo",
  "oneOf": [
    {
      "type": "string"
    },
    {
      "nullable": true
    }
  ]
}

However, I don't think that is valid. (It certainly gives errors when I try to use the generated open api file, e.g. in postman)
I think it needs to be either:

"foo": {
  "title": "foo",
  "type": "string",
  "nullable": true
}

or

"foo": {
  "title": "foo",
  "oneOf": [
    {
      "type": "string"
    },
    {
      "type": "null"
    }
  ]
}

with the former looking slightly neater. Both work correctly when I manually update my generated open api file.

I can see convertNull in Converter.js appears to be making the transform, but don't know if it is as easy as just changing its return value.

[JaredCE]

Thank you so much for bringing this up, and sorry you're facing this issue. I'm actually in the middle of rewriting this library to be a little better tested and to have a better structure, as well as try and do more transformations where possible of JSON schema keywords that aren't in draft-04 and the OpenAPI 3.0.X subset.

I think you're right, it needs to output as:

"foo": {
  "title": "foo",
  "type": "string",
  "nullable": true
}

or at least adding "nullable": true to each type in the array and removing the 'null' type from the array.

I don't believe "type": "null" is valid OpenAPI JSON.

If i can get a fix out later today, I will. it shouldn't be too hard. I am hoping to have the new version of the library out in a few weeks too. If you wanted to try and fix, it'll be the convertTypeArrays function you need to change.

Apologies for this, i'll do my best to get it fixed and up on the serverless-openapi-documenter library ASAP.

[OxonianCambion]

No problem - I think the idea of using the serverless.yml & serverless.doc.yml to generate a comprehensive OpenAPI file, which is then actively shared and used is an excellent one. (Similarly, using the OpenAPI file to set the endpoint documentation seems vastly better than the bizarre mechanism AWS uses, though I have not attempted to actually merge the OpenAPI file with the AWS one.) I'm amazed the AWS support is generally quite weak - still draft-04.

In practice, I maintained a manually curated OpenAPI mirroring changes from the generated one. (I also needed to do the same with the auto-generated draft-07 JsonSchema files which serverless-openapi-documenter uses as part of its input - I had to "flatten" them by removing the very top level of reference & definition. I haven't raised that as an issue on serverless-openapi-documenter as I don't have a good enough understanding to know if I'm doing something wrong. I also don't have the time right now to educate myself properly, and I'm not working in this whole area any more - I can raise it if it is something you think might be relevant.)

Thanks for keeping all of this going btw - again, I'm surprised it isn't used much more widely!

[JaredCE]

Hey @OxonianCambion I think I should have a rather big rewrite out today for this which should fix the issue, though possibly introduce new ones :/

I had to "flatten" them by removing the very top level of reference & definition

I'd be interested to hear more about this. Unfortunately OpenAPI 3.0.X only allows for schema 04 (much like AWS) and doesn't like definitions, however this library combined with serverless-openapi-documenter should be dereferencing and flattening the JSON schema for you. The only thing is, if your $ref is behind a gated resource, you need to provide a way for the de-referencer a way to get access to that resource, which is documented in serverless-openapi-documenter, though perhaps I need to explain it better.

Please raise any issues/questions, whether it's a code issue or a lack of documentation (which might cause a lack of understanding). I realise serverless-openapi-documenter is still missing some key things like authorisation. I hope to rewrite/expand that library over the xmas period, but don't quote me.