From 15dd4549200e2b03db6c3155ecbf32670b6ab252 Mon Sep 17 00:00:00 2001 From: David Biesack Date: Tue, 12 Apr 2016 14:33:47 -0400 Subject: [PATCH 1/2] Describe parameters uniformly with location; use same order and values/case in description. --- versions/2.0.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/versions/2.0.md b/versions/2.0.md index 67f77b4c9f..006f0fa450 100755 --- a/versions/2.0.md +++ b/versions/2.0.md @@ -564,12 +564,12 @@ Describes a single operation parameter. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). -There are five possible parameter types. -* Path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. -* Query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. -* Header - Custom headers that are expected as part of the request. -* Body - The payload that's appended to the HTTP request. Since there can only be one payload, there can only be *one* body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation. -* Form - Used to describe the payload of an HTTP request when either `application/x-www-form-urlencoded`, `multipart/form-data` or both are used as the content type of the request (in Swagger's definition, the [`consumes`](#operationConsumes) property of an operation). This is the only parameter type that can be used to send files, thus supporting the `file` type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4): +There are five possible parameter locations (as specified with the `in` field): +* path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. +* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. +* header - Custom headers that are expected as part of the request. +* body - The payload that's appended to the HTTP request. Since there can only be one payload, there can only be *one* body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation. +* formData - Used to describe the payload of an HTTP request when either `application/x-www-form-urlencoded`, `multipart/form-data` or both are used as the content type of the request (in Swagger's definition, the [`consumes`](#operationConsumes) property of an operation). This is the only parameter type that can be used to send files, thus supporting the `file` type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4): * `application/x-www-form-urlencoded` - Similar to the format of Query parameters but as a payload. For example, `foo=1&bar=swagger` - both `foo` and `bar` are form parameters. This is normally used for simple parameters that are being transferred. * `multipart/form-data` - each parameter takes a section in the payload with an internal header. For example, for the header `Content-Disposition: form-data; name="submit-name"` the name of the parameter is `submit-name`. This type of form parameters is more commonly used for file transfers. @@ -577,9 +577,9 @@ There are five possible parameter types. Field Name | Type | Description ---|:---:|--- name | `string` | **Required.** The name of the parameter. Parameter names are *case sensitive*. -in | `string` | **Required.** The location of the parameter. Possible values are "query", "header", "path", "formData" or "body". +in | `string` | **Required.** The location of the parameter. Possible values are `"path"`, `"query"`, `"header"`, `"body"`, `"formData"`. description | `string` | A brief description of the parameter. This could contain examples of use. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation. -required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) "path", this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. +required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) `"path"`, this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. If [`in`](#parameterIn) is `"body"`: From 725c4999e4538570d6422dd140d98cd4748b62f2 Mon Sep 17 00:00:00 2001 From: David Biesack Date: Tue, 12 Apr 2016 14:33:47 -0400 Subject: [PATCH 2/2] Describe parameters uniformly with location; use same order and values/case in description. Instead of using parameter *types* (which is not defined) and parameter *locations*, just used *location* uniformly; *parameter type* should only refer to the parameterType field, to avoid confusion. Use same order and values/case in the list of locations as in the description's allowed values for `in`. --- versions/2.0.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/versions/2.0.md b/versions/2.0.md index 67f77b4c9f..fd19e17b5c 100755 --- a/versions/2.0.md +++ b/versions/2.0.md @@ -564,12 +564,12 @@ Describes a single operation parameter. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). -There are five possible parameter types. -* Path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. -* Query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. -* Header - Custom headers that are expected as part of the request. -* Body - The payload that's appended to the HTTP request. Since there can only be one payload, there can only be *one* body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation. -* Form - Used to describe the payload of an HTTP request when either `application/x-www-form-urlencoded`, `multipart/form-data` or both are used as the content type of the request (in Swagger's definition, the [`consumes`](#operationConsumes) property of an operation). This is the only parameter type that can be used to send files, thus supporting the `file` type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4): +There are five possible parameter locations (as specified with the `in` field): +* path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. +* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. +* header - Custom headers that are expected as part of the request. +* body - The payload that's appended to the HTTP request. Since there can only be one payload, there can only be *one* body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation. +* formData - Used to describe the payload of an HTTP request when either `application/x-www-form-urlencoded`, `multipart/form-data` or both are used as the content type of the request (in Swagger's definition, the [`consumes`](#operationConsumes) property of an operation). This is the only parameter location that can be used to send files, thus supporting the `file` [type](#parameterType). Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4): * `application/x-www-form-urlencoded` - Similar to the format of Query parameters but as a payload. For example, `foo=1&bar=swagger` - both `foo` and `bar` are form parameters. This is normally used for simple parameters that are being transferred. * `multipart/form-data` - each parameter takes a section in the payload with an internal header. For example, for the header `Content-Disposition: form-data; name="submit-name"` the name of the parameter is `submit-name`. This type of form parameters is more commonly used for file transfers. @@ -577,9 +577,9 @@ There are five possible parameter types. Field Name | Type | Description ---|:---:|--- name | `string` | **Required.** The name of the parameter. Parameter names are *case sensitive*. -in | `string` | **Required.** The location of the parameter. Possible values are "query", "header", "path", "formData" or "body". +in | `string` | **Required.** The location of the parameter. Possible values are `"path"`, `"query"`, `"header"`, `"body"`, `"formData"`. description | `string` | A brief description of the parameter. This could contain examples of use. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation. -required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) "path", this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. +required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) `"path"`, this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. If [`in`](#parameterIn) is `"body"`: @@ -591,7 +591,7 @@ If [`in`](#parameterIn) is any value other than `"body"`: Field Name | Type | Description ---|:---:|--- -type | `string` | **Required.** The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). The value MUST be one of `"string"`, `"number"`, `"integer"`, `"boolean"`, `"array"` or `"file"`. If `type` is `"file"`, the [`consumes`](#operationConsumes) MUST be either `"multipart/form-data"`, `" application/x-www-form-urlencoded"` or both and the parameter MUST be [`in`](#parameterIn) `"formData"`. +type | `string` | **Required.** The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). The value MUST be one of `"string"`, `"number"`, `"integer"`, `"boolean"`, `"array"` or `"file"`. If `type` is `"file"`, the [`consumes`](#operationConsumes) MUST be an array containing either `"multipart/form-data"`, `" application/x-www-form-urlencoded"` or both, and the parameter location MUST be [`in`](#parameterIn) `"formData"`. format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](#dataTypeFormat) for further details. 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`. items | [Items Object](#itemsObject) | **Required if [`type`](#parameterType) is "array".** Describes the type of items in the array.