added schema for all parameters

[fehguy]

This is NOT a complete change, but conceptually it loosens the requirement that all parameters except body parameters be of a simple type. Instead, a schema can be provided for all parameter types.

For parameter types of type body, the schema will be serialized by the consumes attribute. For all other parameter types, a serialization strategy needs to be defined (and is still TBD for definition).

This serialization strategy would be responsible for turning a complex object into JSON, for example.

[fehguy]

This addresses #412, #437, #69, #401, #179 (by inclusion of the schema), #301, #418

For issue #222, we can also add a format for file to indicate the encoding type.

For issue #300, since schemas can be reused, this should address that as well.

This solves #595 if we can define the serialization strategy

[ePaul]

Allow a reference object (i.e. a reference to a schema object) here too?

[webron]

@ePaul - The Schema Object allows a $ref as its value, so there's no need to be explicit about it. It's the same as how body parameters behave today.

[fehguy]

need to reconsider this when looking at 6570 support

[fehguy]

@OAI/tdc please post other comments here--i will not merge until a serialization strategy is provided and there is more time for feedback

[webron]

This does not solve #69 nor #401.

To me the serialization strategy can be controlled by a consumes property at each parameter, which will override any upper-level consumes value (either at the operation or OpenAPI Object level). This will also help resolve #222. This gets tricky since primitives cannot really be serialized as application/json for example, so we may explicitly mention that primitives are passed as-is.

To me, the main issue is arrays and the existing collectionFormat. No mime-type will actually cover the existing cases in it. Brain is a bit fried right now, the only solution I can come up with right now is fairly ugly - will try to think about it more later.

I do not advocate using complex models for query/path/header parameters (body and form are okay) - but in favor of simplicity I 👍 the concept. Just need to work through the open questions.

[fehguy]

• Move type definitions out of serializable parameters
• Add a schema to all
• come up with a serialziation strategy for all non-body parameters

[Vanuan]

Is there any rough implementation?

I'm looking for a simple query parameter of type object serialized into a JSON string.

[ePaul]

@Vanuan I'm not aware of any. We are currently working on the next version of the specification (3.0), and only if that it out, the tools can reliably be updated to support it. (I guess some tools will start implementation earlier, though.)

[Vanuan]

Is there some criteria or time frame for 3.0 to be released?
I mean, are you working towards supporting describing specific APIs, features or do you plan to release new spec each year?
For example you could say that in 3.0 you'd want to support describing such APIs:

• Facebook https://developers.facebook.com/tools/explorer/
• Twitter
• Sailsjs blueprint API http://sailsjs.org/documentation/reference/blueprint-api

Or you could say that you target supporting specific features, like an ability to specify fields like this:
?fields=id,name
or specifying objects in queries like this:
?filter={"name":{"includes":"john"}}
with a full list of those features described somewhere.

Is GitHub issues is the only place or is there some highlevel roadmap with milestone?
In Readme it's mentioned that OpenAPI doesn't plan to support every REST API use case. Does it mean that applications would need to adapt to OpenAPI features to fully employ its benefits?

[webron]

@Vanuan we're aiming for a summer release for 3.0. The changes are done via specific feature requests and not aiming to support specific APIs.

Github issues is the place.

It means that not all APIs could be described with OpenAPI. Whether applications change their APIs or don't use OpenAPI is their call.