mikunn
commented
6 years ago 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
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$schemais 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 convertparameter.descriptiontojsonSchema.description? I suggest we do. 3)parameter.requiredhas two issues. First it is abooleannot 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 removeparameter.required. 4)parameter.allowEmptyValue. See #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 removeparameter.allowEmptyValue5)parameter.name|in|deprecateddo not seem to have any corresponding JSON schema keywords, so I suggest we remove them. 6)parameter.example|examplesandparameter.content.MIME.example|examplescould be converted toexamples. 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|explodeandparameter.content.MIME.encoding: those properties are about how to parse the parameter, not about validation, so I suggest we remove them. 8) Otherwise, mostly useparameter.schemaorparameter.content.MIME.schema9) How to know user passed aParameter Objectand not aSchema Object? We could check for required propertiesnameandin. 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()andrequire("open-api-schema-to-json-schema").fromSchema()This would result in the following:
parameter.schemaif availableparameter.contentis used, we return a{ "MIME": jsonSchema }map. Let's double check that$schemais always available.parameter.description. Everything else we remove.