Add support for OpenAPI 3.0 parameter object

[ehmicky]

Continuation of #9

We should be able to convert an OpenAPI 3.0 Parameter object into a JSON schema v4.

Several issues:

1. a parameter can have one JSON schema per MIME type with parameter.content. One possible solution is to return a { "MIME": jsonSchema, ... } object. Problem is this means this library would return two different types of return values (a MIME map or a simple JSON schema). This would require users to guess which type has been returned. Possible solutions (I personally prefer c) ):
   a) always return a MIME map. I.e. instead of returning a simple JSON schema, return { "*/*": jsonSchema }
   b) add a property like { "isMimeMap": true, ... } when a MIME map was returned
   c) make sure $schema is always included in returned JSON schemas, in which case users can use that to determine if it's a JSON schema or a MIME map
   d) return { anyOf: [{ ...jsonSchema, "x-mime": "MIME" }, ...] } JSON schema
2. should we convert parameter.description to jsonSchema.description? I suggest we do.
3. parameter.required has two issues. First it is a boolean not an array like in JSON schema. Second it could not be converted to an array without returning the parameters object instead of a single parameter. I suggest we remove parameter.required.
4. parameter.allowEmptyValue. See [Feature] Add support for allowEmptyValue #8. The property is very confusing to even the OpenAPI designers themselves. It's unclear what it actually does. It will be deprecated in 3.0.2 and eventually removed. I suggest we remove parameter.allowEmptyValue
5. parameter.name|in|deprecated do not seem to have any corresponding JSON schema keywords, so I suggest we remove them.
6. parameter.example|examples and parameter.content.MIME.example|examples could be converted to examples. But that keyword is JSON schema v6, so I suggest we remove those properties since we only support JSON schema v4.
7. parameter.allowReserved|style|explode and parameter.content.MIME.encoding: those properties are about how to parse the parameter, not about validation, so I suggest we remove them.
8. Otherwise, mostly use parameter.schema or parameter.content.MIME.schema
9. How to know user passed a Parameter Object and not a Schema Object? We could check for required properties name and in. This would work but might not be extensible if we want to add other definitions, or for future OpenAPI versions. Another solution (which I would suggest) would be to export another function, e.g. require("open-api-schema-to-json-schema").fromParameter() and require("open-api-schema-to-json-schema").fromSchema()

This would result in the following:

• we use parameter.schema if available
• if parameter.content is used, we return a { "MIME": jsonSchema } map. Let's double check that $schema is always available.
• we keep parameter.description. Everything else we remove.

[mikunn]

Thank you, this is a very good overview and I agree with everything!

Here's some additional throughts:

2. if the schema already has description, just replace it with the root description by default. We can provide an option later to do something else.

9. Yes, let's be explicit and go with require("open-api-schema-to-json-schema").fromParameter(). We can also add require("open-api-schema-to-json-schema").fromSchema() which does the same as require("open-api-schema-to-json-schema")() so that we don't break the API.

[ehmicky]

Good point on number 2! Agrees with your comment on number 9 as well.

Would you like me to work on a PR for this?

[mikunn]

Please be free to work on a PR, that would be very helpful!

I modularized the codebase a bit. There's lib/converters/schema.js. You can add lib/conventers/parameter.js or something. There's also lib/convert.js which works just as an interface between index.js and lib/converters/*.js. Be free to remove the lib/convert.js and use the converters directly to avoid the unnecessary additional steps.

[ehmicky]

Done in #25