Skip to content

added parameter object updates for #840 #842

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 18, 2016
Merged

added parameter object updates for #840 #842

merged 2 commits into from
Nov 18, 2016

Conversation

fehguy
Copy link
Contributor

@fehguy fehguy commented Nov 18, 2016

No description provided.

@fehguy
Copy link
Contributor Author

fehguy commented Nov 18, 2016

@OAI/tdc This PR addresses the parameter object docs of #589. It introduces two concepts which have been discussed but not agreed upon:

  1. Parameters have previously had a simple definition type. For example:
in: query
type: string
name: search

To preserve this simplicity, I have added back this section from the 2.0 specification.

  1. To support complex parameters, and address the serialization needs, we introduce, instead of the schema property, the content property as used elsewhere:
in: query
name: search
content:
  application/json:
    schema:
      type: object

This allows the following:

  • defining serialization strategies for complex types
  • keeping a simple structure for the 99% of use cases where primitives and arrays of primitives are passed

@webron
Copy link
Member

webron commented Nov 18, 2016

Regarding the simple case - restrictions related to formData parameters should be removed as it no longer exists as a type.

<a name="parameterFormat"></a>format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](#dataTypeFormat) for further details.
<a name="parameterAllowEmptyValue"/>allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for either `query` or `formData` parameters and allows you to send a parameter with a name only or an empty value. Default value is `false`.
<a name="parameterItems"></a>items | [Items Object](#itemsObject) | **Required if [`type`](#parameterType) is "array".** Describes the type of items in the array.
<a name="parameterCollectionFormat"></a>collectionFormat | `string` | Determines the format of the array if type array is used. Possible values are: <ul><li>`csv` - comma separated values `foo,bar`. <li>`ssv` - space separated values `foo bar`. <li>`tsv` - tab separated values `foo\tbar`. <li>`pipes` - pipe separated values <code>foo&#124;bar</code>. <li>`multi` - corresponds to multiple parameter instances instead of multiple values for a single instance `foo=bar&foo=baz`. This is valid only for parameters [`in`](#parameterIn) "query" or "formData". </ul> Default value is `csv`.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably take this out

@webron
Copy link
Member

webron commented Nov 18, 2016

@fehguy to clean out the PR and be merged. @whitlockjc and and @darrelmiller to discuss additional options for simplification.

@fehguy fehguy merged commit 3356090 into OpenAPI.next Nov 18, 2016
@fehguy fehguy deleted the issue-840 branch November 18, 2016 18:34
AndersDJohnson pushed a commit to AndersDJohnson/OpenAPI-Specification that referenced this pull request Apr 8, 2019
added parameter object updates for OAI#840
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants