From 650000a84424b3a3c7ae8f375e0774210299daa3 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Wed, 28 Sep 2016 23:19:33 -0700 Subject: [PATCH] updated #761 for naming consistency --- versions/3.0.md | 520 ++++++++++++++++++++++++++++-------------------- 1 file changed, 308 insertions(+), 212 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index dcaaeb57db..6119777f95 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -58,7 +58,7 @@ YAML, being a superset of JSON, can be used as well to represent a OAS (OpenAPI For example, if a field is said to have an array value, the JSON array representation will be used: -```js +```json { "field" : [...] } @@ -128,8 +128,6 @@ Field Name | Type | Description openapi | `string` | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document. info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed. hosts | [Hosts Object](#hostsObject) | An array of Host objects which provide `scheme`, `host`, `port`, and `basePath` in an associative manner. -consumes | [`string`] | A list of media types the APIs can consume. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under [Media Types](#mediaTypes). -produces | [`string`] | A list of media types the APIs can produce. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under [Media Types](#mediaTypes). responses | [Responses] paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. @@ -167,7 +165,7 @@ Field Pattern | Type | Description ##### Info Object Example: -```js +```json { "title": "Swagger Sample App", "description": "This is a sample server Petstore server.", @@ -231,7 +229,7 @@ Field Pattern | Type | Description ##### Contact Object Example: -```js +```json { "name": "API Support", "url": "http://www.swagger.io/support", @@ -264,7 +262,7 @@ Field Pattern | Type | Description ##### License Object Example: -```js +```json { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" @@ -307,21 +305,22 @@ Field Pattern | Type | Description ##### Paths Object Example -```js +```json { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to", - "produces": [ - "application/json" - ], "responses": { "200": { "description": "A list of pets.", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/pet" + "representations": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/pet" + } + } } } } @@ -335,15 +334,15 @@ Field Pattern | Type | Description /pets: get: description: Returns all pets from the system that the user has access to - produces: - - application/json responses: '200': description: A list of pets. - schema: - type: array - items: - $ref: '#/definitions/pet' + representations: + application/json: + schema: + type: array + items: + $ref: '#/definitions/pet' ``` #### Path Item Object @@ -379,30 +378,34 @@ Field Pattern | Type | Description ##### Path Item Object Example -```js +```json { "get": { "description": "Returns pets based on ID", "summary": "Find pets by ID", "operationId": "getPetsById", - "produces": [ - "application/json", - "text/html" - ], "responses": { "200": { "description": "pet response", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/Pet" + "representations": { + "*": { + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/Pet" + } + } } } }, "default": { "description": "error payload", - "schema": { - "$ref": "#/definitions/ErrorModel" + "representations": { + "*": { + "schema": { + "$ref": "#/definitions/ErrorModel" + } + } } } } @@ -428,20 +431,21 @@ get: description: Returns pets based on ID summary: Find pets by ID operationId: getPetsById - produces: - - application/json - - text/html responses: '200': description: pet response - schema: - type: array - items: - $ref: '#/definitions/Pet' + representations: + application/json: + schema: + type: array + items: + $ref: '#/definitions/Pet' default: description: error payload - schema: - $ref: '#/definitions/ErrorModel' + representations: + "*": + schema: + $ref: '#/definitions/ErrorModel' parameters: - name: id in: path @@ -466,8 +470,6 @@ Field Name | Type | Description description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions. -consumes | [`string`] | A list of media types the operation can consume. This overrides the [`consumes`](#oasConsumes) definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Media Types](#mediaTypes). -produces | [`string`] | A list of media types the operation can produce. This overrides the [`produces`](#oasProduces) definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Media Types](#mediaTypes). parameters | [[Parameter Object](#parameterObject) | [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it, but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's parameters](#oasParameters). requestBody | [[Request Body Object](#requestBodyObject) | [Reference Object](#referenceObject)] | The request body applicable for this operation. responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation. @@ -486,7 +488,7 @@ Field Pattern | Type | Description ##### Operation Object Example -```js +```json { "tags": [ "pet" @@ -494,13 +496,6 @@ Field Pattern | Type | Description "summary": "Updates a pet in the store with form data", "description": "", "operationId": "updatePetWithForm", - "consumes": [ - "application/x-www-form-urlencoded" - ], - "produces": [ - "application/json", - "application/xml" - ], "parameters": [ { "name": "petId", @@ -549,11 +544,6 @@ tags: summary: Updates a pet in the store with form data description: "" operationId: updatePetWithForm -consumes: -- application/x-www-form-urlencoded -produces: -- application/json -- application/xml parameters: - name: petId in: path @@ -601,7 +591,7 @@ Field Pattern | Type | Description ##### External Documentation Object Example -```js +```json { "description": "Find more info here", "url": "https://swagger.io" @@ -623,7 +613,7 @@ 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. -* 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 the OpenAPI Specification'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): +* 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 representations. 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. @@ -654,7 +644,7 @@ Field Pattern | Type | Description A header parameter with an array of 64 bit integer numbers: -```js +```json { "name": "token", "in": "header", @@ -685,7 +675,7 @@ schema: ``` A path parameter of a string value: -```js +```json { "name": "username", "in": "path", @@ -707,7 +697,7 @@ schema: ``` An optional query parameter of a string value, allowing multiple values by repeating the query parameter: -```js +```json { "name": "id", "in": "query", @@ -736,7 +726,7 @@ schema: ``` A form data with file type for a file upload: -```js +```json { "name": "avatar", "in": "formData", @@ -761,13 +751,10 @@ schema: Describes a single request body. -The `Content-Type` of the request body must be specified by the `consumes` attribute, either at the [top-level](#oasConsumes) or [operation level](#operationConsumes). - ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | A brief description of the request body. This could contain examples of use. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body. examples | [Examples Object](#examplesObject) | Examples of the request body, referenced by media type. required | `boolean` | Determines if the request body is required in the request. Defaults to `true`. @@ -775,53 +762,72 @@ Field Name | Type | Description ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- +`*` | [Schema Object](#schemaObject) | The schema defining the request body. ^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Vendor Extensions](#vendorExtensions) for further details. ##### Request Body Examples A request body with a referenced model definition. -```js +```json { "description": "user to add to the system", - "schema": { - "$ref": "#/definitions/User" - }, - "examples": { - "application/json": { - "$ref": 'http://foo.bar#/examples/address-example.json' - 'application/xml': - $ref: 'http://foo.bar#/examples/address-example.xml' - 'text/plain': - $ref: 'http://foo.bar#/examples/address-example.txt' - default: - $ref: 'http://foo.bar#/examples/address-example.whatever' + "representations": { + "application/json": { + "schema": { + "$ref": "#/definitions/User" + }, + "example": { + "$ref": "http://foo.bar#/examples/address-example.json" + } + }, + "application/xml": { + "schema": { + "$ref": "#/definitions/User" + }, + "example": { + "$ref": "http://foo.bar#/examples/address-example.xml" + } + }, + "*": { + "example": { + $ref: "http://foo.bar#/examples/address-example.whatever" + } + } + } } ``` ```yaml description: user to add to the system -schema: - $ref: '#/definitions/User' -examples: - 'application/json': - $ref: 'http://foo.bar/examples/user-example.json' - 'application/xml': - $ref: 'http://foo.bar/examples/user-example.xml' - 'text/plain': - $ref: 'http://foo.bar/examples/user-example.txt' - default: - $ref: 'http://foo.bar/examples/user-example.whatever' +representations: + 'application/json': + schema: + $ref: '#/definitions/User' + example: + $ref: 'http://foo.bar/examples/user-example.json' + 'application/xml': + schema: + $ref: '#/definitions/User' + example: + $ref: 'http://foo.bar/examples/user-example.xml' + '*': + schema: + $ref: 'http://foo.bar/examples/user-example.whatever' ``` A body parameter that is an array of string values: -```js +```json { "description": "user to add to the system", - "schema": { - "type": "array", - "items": { - "type": "string" + "representations": { + "text/plain": { + "schema": { + "type": "array", + "items": { + "type": "string" + } + } } } } @@ -830,10 +836,12 @@ A body parameter that is an array of string values: ```yaml description: user to add to the system required: true -schema: - type: array - items: - type: string +representations: + text/plain: + schema: + type: array + items: + type: string ``` #### Items Object @@ -872,7 +880,7 @@ Field Pattern | Type | Description Items must be of type string and have the minimum length of 2 characters: -```js +```json { "type": "string", "minLength": 2 @@ -886,14 +894,14 @@ minLength: 2 An array of arrays, the internal array being of type integer, numbers must be between 0 and 63 (inclusive): -```js +```json { - "type": "array", - "items": { - "type": "integer", - "minimum": 0, - "maximum": 63 - } + "type": "array", + "items": { + "type": "integer", + "minimum": 0, + "maximum": 63 + } } ``` @@ -926,7 +934,7 @@ It can be used to cover undeclared responses. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- -{[HTTP Status Code](#httpCodes)} | [Response Object](#responseObject) | [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name (one property per HTTP status code). Describes the expected response for that HTTP status code. [Reference Object](#referenceObject) can be used to link to a response that is defined at the [OpenAPI Object's responses](#oasResponses) section. This field must quoted for compatibility between JSON and YAML (i.e. "200"), and may contain the uppercase character, `X` to designate a wildcard, such as `2XX` to represent all response codes between `[200-299]`. +[HTTP Status Code](#httpCodes) | [Response Object](#responseObject) | [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name (one property per HTTP status code). Describes the expected response for that HTTP status code. [Reference Object](#referenceObject) can be used to link to a response that is defined at the [OpenAPI Object's responses](#oasResponses) section. This field must quoted for compatibility between JSON and YAML (i.e. "200"), and may contain the uppercase character, `X` to designate a wildcard, such as `2XX` to represent all response codes between `[200-299]`. ^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details. @@ -934,18 +942,26 @@ Field Pattern | Type | Description A 200 response for successful operation and a default response for others (implying an error): -```js +```json { "200": { "description": "a pet to be returned", - "schema": { - "$ref": "#/definitions/Pet" + "representations": { + "application/json": { + "schema": { + "$ref": "#/definitions/Pet" + } + } } }, "default": { "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/ErrorModel" + "representations": { + "application/json": { + "schema": { + "$ref": "#/definitions/ErrorModel" + } + } } } } @@ -954,12 +970,16 @@ A 200 response for successful operation and a default response for others (imply ```yaml '200': description: a pet to be returned - schema: - $ref: '#/definitions/Pet' + representations: + application/json + schema: + $ref: '#/definitions/Pet' default: description: Unexpected error - schema: - $ref: '#/definitions/ErrorModel' + representations: + '*': + schema: + $ref: '#/definitions/ErrorModel' ``` #### Response Object @@ -969,7 +989,6 @@ Describes a single response from an API Operation, including design-time, static Field Name | Type | Description ---|:---:|--- description | `string` | **Required.** A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -schema | [Schema Object](#schemaObject) | A definition of the response structure. It can be a primitive, an array or an object. If this field does not exist, it means no content is returned as part of the response. As an extension to the [Schema Object](#schemaObject), its root `type` value may also be `"file"`. This SHOULD be accompanied by a relevant `produces` media type. headers | [Headers Object](#headersObject) | A list of headers that are sent with the response. examples | [Example Object](#exampleObject) | An example of the response message. links | [Links Object](#linksObject) | An object representing operations related to the response payload. @@ -979,19 +998,26 @@ Field Name | Type | Description Field Pattern | Type | Description ---|:---:|--- +`*` | [Schema Object](#schemaObject)| [Reference Object](#referenceObject) | A schema describing the response value for a specific `Content-Type` ^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details. +Representations may take the form of a wildcard (`*`) to designate any `Content-Type`, or a regular expression for matching a specific type + ##### Response Object Examples Response of an array of a complex type: -```js +```json { "description": "A complex object array response", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/VeryComplexType" + "representations": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/VeryComplexType" + } + } } } } @@ -999,36 +1025,48 @@ Response of an array of a complex type: ```yaml description: A complex object array response -schema: - type: array - items: - $ref: '#/definitions/VeryComplexType' +representations: + application/json: + schema: + type: array + items: + $ref: '#/definitions/VeryComplexType' ``` Response with a string type: -```js +```json { "description": "A simple string response", - "schema": { - "type": "string" + "representations": { + "schema": { + "text/plain": { + "type": "string" + } + } } } ``` ```yaml description: A simple string response -schema: - type: string +representations: + text/plain: + schema: + type: string ``` Response with headers: -```js +```json { "description": "A simple string response", - "schema": { - "type": "string" + "representations": { + "text/plain": { + "schema": { + "type": "string" + } + } }, "headers": { "X-Rate-Limit-Limit": { @@ -1049,8 +1087,11 @@ Response with headers: ```yaml description: A simple string response -schema: - type: string +representations: + text/plain: + schema: + type: string + example: 'whoa!' headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period @@ -1065,7 +1106,7 @@ headers: Response with no return value: -```js +```json { "description": "object created" } @@ -1087,7 +1128,7 @@ Field Pattern | Type | Description Rate-limit headers: -```js +```json { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", @@ -1129,7 +1170,7 @@ Field Pattern | Type | Description Example request or response for application/json media type of a Pet data type: -```js +```json { "application/json": { "name": "Puma", @@ -1214,9 +1255,9 @@ For example: ```json [ - { "color": "red" }, - { "color": "green" }, - { "color": "blue" } + { "color": "red" }, + { "color": "green" }, + { "color": "blue" } ] ``` @@ -1263,12 +1304,14 @@ paths: responses: 200: description: the user being returned - schema: - type: object - properties: - uuid: the unique user id - type: string - format: uuid + representations: + application/json: + schema: + type: object + properties: + uuid: the unique user id + type: string + format: uuid ``` Can be used in a link like this: @@ -1334,8 +1377,10 @@ paths: responses: 200: description: The User - schema: - $ref: '#/components/definitions/user' + representations: + application/json: + schema: + $ref: '#/components/definitions/user' links: userRepositories: $ref: '#/components/links/UserRepositories' @@ -1350,10 +1395,12 @@ paths: responses: 200: description: repositories owned by the supplied user - schema: - type: array - items: - $ref: '#/components/definitions/repository' + representations: + application/json: + schema: + type: array + items: + $ref: '#/components/definitions/repository' links: userRepository: $ref: '#/components/links/UserRepository' @@ -1372,8 +1419,10 @@ paths: responses: 200: description: The repository - schema: - $ref: '#/components/definitions/repository' + representations: + application/json: + schema: + $ref: '#/components/definitions/repository' links: repositoryPullRequests: $ref: '#/components/links/RepositoryPullRequests' @@ -1399,10 +1448,12 @@ paths: responses: 200: description: an array of pull request objects - schema: - type: array - items: - $ref: '#/components/definitions/pullrequest' + representations: + application/json: + schema: + type: array + items: + $ref: '#/components/definitions/pullrequest' /2.0/repositories/{username}/{slug}/pullrequests/{pid}: get: operationId: getPullRequestsById @@ -1422,8 +1473,10 @@ paths: responses: 200: description: a pull request object - schema: - $ref: '#/components/definitions/pullrequest' + representations: + application/json: + schema: + $ref: '#/components/definitions/pullrequest' links: $ref: '#/components/links/PullRequestMerge' /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge: @@ -1587,7 +1640,7 @@ Field Pattern | Type | Description A simple header with of an integer type: -```js +```json { "description": "The number of allowed requests in the current period", "type": "integer" @@ -1618,7 +1671,7 @@ Field Pattern | Type | Description ##### Tag Object Example -```js +```json { "name": "pet", "description": "Pets operations" @@ -1649,19 +1702,15 @@ definitions: example: $ref: http://foo.bar#/examples/name-example -# in a request body, note the plural `examples` as the content-type is set by `consumes`: +# in a request body, note the plural `examples` as the content-type is set to `*`: requestBody: - schema: - $ref: '#/definitions/Address' - examples: - 'application/json': - $ref: 'http://foo.bar#/examples/address-example.json' - 'application/xml': - $ref: 'http://foo.bar#/examples/address-example.xml' - 'text/plain': - $ref: 'http://foo.bar#/examples/address-example.txt' - default: - $ref: 'http://foo.bar#/examples/address-example.whatever' + representations: + 'application/json': + schema: + $ref: '#/definitions/Address' + examples: + - {"foo": "bar"} + - {"bar": "baz"} # in a parameter @@ -1676,11 +1725,12 @@ definitions: responses: 200: description: your car appointment has been booked - schema: - $ref: '#/definitions/SuccessResponse' - examples: - 'application/json': - $ref: http://foo.bar#/examples/address-example.json + representations: + application/json: + schema: + $ref: '#/definitions/SuccessResponse' + example: + $ref: http://foo.bar#/examples/address-example.json ``` #### Reference Object @@ -1698,7 +1748,7 @@ Field Name | Type | Description ##### Reference Object Example -```js +```json { "$ref": "#/definitions/Pet" } @@ -1709,7 +1759,7 @@ $ref: '#/definitions/Pet' ``` ##### Relative Schema File Example -```js +```json { "$ref": "Pet.json" } @@ -1720,7 +1770,7 @@ $ref: 'Pet.yaml' ``` ##### Relative Files With Embedded Schema Example -```js +```json { "$ref": "definitions.json#/Pet" } @@ -1780,6 +1830,7 @@ Field Name | Type | Description xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. example | Any | A free-form property to include an example of an instance for this schema. +examples | Any | An array of free-formed properties to include examples for this schema. deprecated | `boolean` | Specifies that a schema is deprecated and should be transitioned out of usage. ##### Patterned Objects @@ -1811,10 +1862,10 @@ The [XML Object](#xmlObject) contains additional information about the available Unlike previous versions of Swagger, OpenAPI Schema definitions can be used to describe primitive and arrays as well. -```js +```json { - "type": "string", - "format": "email" + "type": "string", + "format": "email" } ``` @@ -1825,7 +1876,7 @@ format: email ###### Simple Model -```js +```json { "type": "object", "required": [ @@ -1866,7 +1917,7 @@ properties: For a simple string to string mapping: -```js +```json { "type": "object", "additionalProperties": { @@ -1883,7 +1934,7 @@ additionalProperties: For a string to model mapping: -```js +```json { "type": "object", "additionalProperties": { @@ -1900,7 +1951,7 @@ additionalProperties: ###### Model with Example -```js +```json { "type": "object", "properties": { @@ -1937,9 +1988,54 @@ example: id: 1 ``` +###### Model with Examples + +```json +{ + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "examples": [ + { + "name": "Puma", + "id": 1 + }, { + "name": "Ferguson", + "id": 2 + }] +} +``` + +```yaml +type: object +properties: + id: + type: integer + format: int64 + name: + type: string +required: +- name +examples: + - name: Puma + id: 1 + - name: Ferguson + id: 2 +``` + ###### Models with Composition -```js +```json { "definitions": { "ErrorModel": { @@ -2008,7 +2104,7 @@ definitions: ###### Models with Polymorphism Support -```js +```json { "definitions": { "Pet": { @@ -2157,7 +2253,7 @@ The examples of the XML object definitions are included inside a property defini Basic string property: -```js +```json { "animals": { "type": "string" @@ -2176,7 +2272,7 @@ animals: Basic string array property ([`wrapped`](#xmlWrapped) is `false` by default): -```js +```json { "animals": { "type": "array", @@ -2202,7 +2298,7 @@ animals: ###### XML Name Replacement -```js +```json { "animals": { "type": "string", @@ -2229,7 +2325,7 @@ animals: In this example, a full model definition is shown. -```js +```json { "Person": { "type": "object", @@ -2279,7 +2375,7 @@ Person: Changing the element names: -```js +```json { "animals": { "type": "array", @@ -2309,7 +2405,7 @@ animals: The external `name` property has no effect on the XML: -```js +```json { "animals": { "type": "array", @@ -2344,7 +2440,7 @@ animals: Even when the array is wrapped, if no name is explicitly defined, the same name will be used both internally and externally: -```js +```json { "animals": { "type": "array", @@ -2376,7 +2472,7 @@ animals: To overcome the above example, the following definition can be used: -```js +```json { "animals": { "type": "array", @@ -2413,7 +2509,7 @@ animals: Affecting both internal and external names: -```js +```json { "animals": { "type": "array", @@ -2452,7 +2548,7 @@ animals: If we change the external element but not the internal ones: -```js +```json { "animals": { "type": "array", @@ -2509,7 +2605,7 @@ my\org\User ##### Definitions Object Example -```js +```json { "Category": { "type": "object", @@ -2572,7 +2668,7 @@ Field Pattern | Type | Description ##### Parameters Definition Object Example -```js +```json { "skipParam": { "name": "skip", @@ -2626,7 +2722,7 @@ Field Pattern | Type | Description ##### Responses Definitions Object Example -```js +```json { "NotFound": { "description": "Entity not found." @@ -2666,7 +2762,7 @@ Field Pattern | Type | Description ##### Security Definitions Object Example -```js +```json { "api_key": { "type": "apiKey", @@ -2726,7 +2822,7 @@ Field Name | Type | Description ###### Basic Authentication Sample -```js +```json { "type": "basic" } @@ -2738,7 +2834,7 @@ type: basic ###### API Key Sample -```js +```json { "type": "apiKey", "name": "api_key", @@ -2754,7 +2850,7 @@ in: header ###### Implicit OAuth2 Sample -```js +```json { "type": "oauth2", "authorizationUrl": "http://swagger.io/api/oauth/dialog", @@ -2793,7 +2889,7 @@ Field Pattern | Type | Description ##### Scopes Object Example -```js +```json { "write:pets": "modify pets in your account", "read:pets": "read your pets" @@ -2822,7 +2918,7 @@ Field Pattern | Type | Description ###### Non-OAuth2 Security Requirement -```js +```json { "api_key": [] } @@ -2834,7 +2930,7 @@ api_key: [] ###### OAuth2 Security Requirement -```js +```json { "petstore_auth": [ "write:pets",