diff --git a/versions/3.0.md b/versions/3.0.md index fd613139ee..66a3004130 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -53,12 +53,12 @@ Additional utilities can also take advantage of the resulting files, such as tes - [Callback Object](#callbackObject) - [Headers Object](#headersObject) - [Example Object](#exampleObject) + - [Examples Array](#examplesArray) - [Links Object](#linksObject) - [Link Object](#linkObject) - [Link Parameters Object](#linkParametersObject) - [Header Object](#headerObject) - [Tag Object](#tagObject) - - [Examples Object](#examplesObject) - [Reference Object](#referenceObject) - [Schema Object](#schemaObject) - [XML Object](#xmlObject) @@ -614,7 +614,7 @@ This object can be extended with [Specification Extensions](#specificationExtens "schema": { "type": "array", "items": { - "$ref": "#/components/schemas/pet" + "$ref": "#/components/schemas/Pet" } } } @@ -638,7 +638,7 @@ This object can be extended with [Specification Extensions](#specificationExtens schema: type: array items: - $ref: '#/components/schemas/pet' + $ref: '#/components/schemas/Pet' ``` #### Path Item Object @@ -1128,20 +1128,20 @@ A request body with a referenced model definition. "schema": { "$ref": "#/components/schemas/User" }, - "examples": [ "http://foo.bar/examples/user-example.json" ] + "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user" ] }, "application/xml": { "schema": { "$ref": "#/components/schemas/User" }, - "examples": [ "http://foo.bar/examples/user-example.xml" ] + "examples": [ "http://foo.bar/other-api.yaml#/components/xmlUser" ] }, "text/plain": { - "examples": [ "http://foo.bar/examples/user-example.txt" ] + "examples": [ "http://foo.bar/other-api.yaml#/components/examples/textUser" ] }, "*/*": { "example": { - "$ref": "http://foo.bar/examples/user-example.whatever" + "$ref": "http://foo.bar/other-api.yaml#/components/examples/anyUser" } } } @@ -1155,18 +1155,18 @@ content: schema: $ref: '#/components/schemas/User' examples: - - 'http://foo.bar/examples/user-example.json' + - 'http://foo.bar/other-api.yaml#/components/examples/user' 'application/xml': schema: $ref: '#/components/schemas/User' examples: - - 'http://foo.bar/examples/user-example.xml' + - 'http://foo.bar/other-api.yaml#/components/xmlUser' 'text/plain': examples: - - 'http://foo.bar/examples/user-example.txt' + - 'http://foo.bar/other-api.yaml#/components/examples/textUser' '*/*': example: - $ref: 'http://foo.bar/examples/user-example.whatever' + $ref: 'http://foo.bar/other-api.yaml#/components/examples/anyUser' ``` A body parameter that is an array of string values: @@ -1822,24 +1822,34 @@ X-Rate-Limit-Reset: #### Example Object -Allows sharing examples for operation requests and responses. This object can either be a freeform object, array or primitive value. To represent examples of media types that cannot naturally represented in the OpenAPI definition, a string value can be used to contain the example with escaping where necessary. +Allows sharing examples for operation requests and responses and other content. This object can either be a freeform object, array, or primitive value. +To represent examples of media types that cannot naturally represented in the OpenAPI definition, a string value can be used to contain the example with escaping where necessary. -##### Example Example +Anywhere an `example` may be given (including in and [Examples Array](#examplesArray)), +a [Reference Object](#referenceObject) MAY be used, with the +explicit restriction that examples having a JSON format with an object named +`$ref` are *not* allowed. -Example representation for application/json media type of a Pet data type: +The value SHOULD be compatible with the type schema +for the content that it is accompanying. Tooling implementations MAY choose to +validate compatibility automatically, and reject the example value(s) if they +are not compatible. + +##### Example Object Example + +Example representation for `application/json` media type of a Pet data type: ```json - { - "name": "Puma", - "type": "Dog", - "color": "Black", - "gender": "Female", - "breed": "Mixed" - } +{ + "name": "Puma", + "type": "Dog", + "color": "Black", + "gender": "Female", + "breed": "Mixed" +} ``` ```yaml - name: Puma type: Dog color: Black @@ -1848,6 +1858,158 @@ breed: Mixed ``` +A [Parameter Object](#parameterObject) referencing an example component from another OpenAPI definition: + +```json + "parameters" : [ { + "name" : "zipCode", + "in" : "query", + "schema" : { + "type" : "string", + "format" : "zip-code", + "example" : { + "$ref" : "http://foo.bar/other-api.yaml#/components/examples/ZipCode" + } + } + } ] +``` +```yaml + parameters: + - name: 'zipCode' + in: 'query' + schema: + type: 'string' + format: 'zip-code' + example: + $ref: 'http://foo.bar/other-api.yaml#/components/examples/ZipCode' +``` + +Several examples defined in the [Component Object](#Component Object) `examples` object: + +```json + "components" : { + "examples" : { + "ZipCode" : "12345", + "Address" : { + "street" : "119 N Weatherly Ave", + "street2" : "Apt. D", + "city" : "Minneapolis", + "state" : "MN", + "zip" : "55405", + "type" : "residence" + }, + "TextAddress" : "119 N Weatherly Ave, Apt. D, Minneapolis. MN 55405", + "SimpleXmlAddress" : "
119 N Weatherly Ave55405
" + } + } +``` + +```yaml +components: + examples: + ZipCode: '12345' + Address: + street: 119 N Weatherly Ave + street2: Apt. D + city: Minneapolis + state: MN + zip : '55405' + type: residence + TextAddress: "119 N Weatherly Ave, Apt. D, Minneapolis. MN 55405" + SimpleXmlAddress: + "
119 N Weatherly Ave55405
" +``` + +#### Examples Array + +Instead of a single `example`, you may provide an array of +[Example Object](#exampleObject) values named `examples`. +`example` and `examples` are mutually exclusive. + +##### Examples Array Examples + +Use of `examples` in a model [Schema Object](#schemaObject): + +```json + "components" : { + "schemas" : { + "address" : { + "properties" : { + "name" : { + "type" : "string" + } + }, + "examples" : [ { + "$ref" : "#/components/examples/Identity" + }, { + "$ref" : "#/components/examples/Identity2" + } ] + } + } + } +``` + +```yaml +components: + schemas: + Address: + examples: + - $ref: "#/components/examples/Identity" + - $ref: "#/components/examples/Identity2" +``` + +Below is an `examples` array in a [Request Body Object](#requestBodyObject), +showing two inline examples and references +to examples in the document's [Components Object](#componentsObject): + +```json + "requestBody" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Address" + }, + "examples" : [ { + "street" : "119 N Weatherly Ave.", + "zip" : "55405" + }, { + "$ref" : "#/components/examples/Address" + } ] + }, + "application/xml" : { + "examples" : [ { + "$ref" : "#/components/examples/SimpleXmlAddress" + }, { + "$ref" : "#/components/examples/CompleteXmlAddress" + } ] + }, + "text/plain" : { + "examples" : [ { + "$ref" : "#/components/examples/TextAddress" + } ] + } + } + } +``` + +```yaml + requestBody: + content: + 'application/json': + schema: + $ref: '#/components/schemas/Address' + examples: + - { "street": "119 N Weatherly Ave.", "zip" : "55405" } + - $ref: '#/components/examples/Address' + 'application/xml': + examples: + - $ref: '#/components/examples/SimpleXmlAddress' + - $ref: '#/components/examples/CompleteXmlAddress' + 'text/plain': + examples: + - $ref: '#/components/examples/TextAddress' +``` + #### Links Object The links object represents a set of possible design-time links for a response. The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations. @@ -2355,7 +2517,12 @@ description: Pets operations #### Examples Object -Anywhere an `example` may be given, a JSON Reference MAY be used, with the +Instead of a single `example`, you may provide an array of +[Example Object](#exampleObject) values named `examples'. +`example` and `examples` are mutually exclusive. + +Anywhere an `example` may be given (including in the Examples Object array), +a JSON Reference MAY be used, with the explicit restriction that examples having a JSON format with object named `$ref` are not allowed. This does mean that `example`, structurally, can be either a string primitive or an object, similar to `additionalProperties`. @@ -2365,33 +2532,117 @@ for the value that it is accompanying. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if they are not compatible. +Here is a single `example` in a model [Schema Object](#schemaObject): + +```json + "components" : { + "schemas" : { + "identity" : { + "properties" : { + "name" : { + "type" : "string" + } + }, + "example" : { + "$ref" : "#/components/examples/identity" + } + } + } + } +``` + ```yaml -# in a model -schemas: - properties: - name: - type: string +components: + schemas: + identity: + properties: + name: + type: string example: - $ref: http://foo.bar#/examples/name-example + $ref: "#/components/examples/identity" +``` + +Below is an `examples` array in a [Request Body Object](#requestBodyObject), +showing two in-line examples and references +to examples in the document's [Components Object](#componentsObject): -# in a request body, note the plural `examples` as the Content-Type is set to `*`: +```json + "requestBody" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Address" + }, + "examples" : [ { + "street" : "119 N Weatherly Ave.", + "zip" : "55405" + }, { + "street" : "119 N Weatherly Ave", + "street2" : "Apt. D", + "city" : "Minneapolis", + "state" : "MN", + "zip" : "55405", + "type" : "residence" + }, { + "$ref" : "#/components/examples/altAddress" + } ] + }, + "application/xml" : { + "examples" : [ { + "$ref" : "#/components/examples/simpleXmlAddress" + }, { + "$ref" : "#/components/examples/completeXmlAddress" + } ] + }, + "text/plain" : { + "examples" : [ { + "$ref" : "#/components/examples/textAddress" + } ] + } + } + } +``` + +```yaml requestBody: content: 'application/json': schema: $ref: '#/components/schemas/Address' examples: - - {"foo": "bar"} - - {"bar": "baz"} + - { "street": "119 N Weatherly Ave.", "zip" : "55405" } + - street: 119 N Weatherly Ave + street2: Apt. D + city: Minneapolis + state: MN + zip : '55405' + type: residence + - $ref: '#/components/examples/altAddress' 'application/xml': examples: - - $ref: 'http://foo.bar#/examples/address-example.xml' + - $ref: '#/components/examples/simpleXmlAddress' + - $ref: '#/components/examples/completeXmlAddress' 'text/plain': examples: - - $ref: 'http://foo.bar#/examples/address-example.txt' - -# in a parameter + - $ref: '#/components/examples/textAddress' +``` +This shows referencing an example component from another OpenAPI definition, +in a [Parameter Object](#parameterObject): +```json + "parameters" : [ { + "name" : "zipCode", + "in" : "query", + "schema" : { + "type" : "string", + "format" : "zip-code", + "example" : { + "$ref" : "http://foo.bar/other-api.yaml#/components/examples/zipCode" + } + } + } ] +``` +```yaml parameters: - name: 'zipCode' in: 'query' @@ -2399,8 +2650,29 @@ schemas: type: 'string' format: 'zip-code' example: - $ref: 'http://foo.bar#/examples/zip-example' -# in a response, note the plural `examples`: + $ref: 'http://foo.bar/other-api.yaml#/components/examples/zipCode' +``` + +Finally, in a [Response Object](#responseObject): + +```json + "responses" : { + "200" : { + "description" : "your car appointment has been booked", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/SuccessResponse" + }, + "example" : { + "$ref" : "http://foo.bar/other-api.yaml#/components/examples/successResponse" + } + } + } + } +}``` + +```yaml responses: '200': description: your car appointment has been booked @@ -2409,7 +2681,7 @@ schemas: schema: $ref: '#/components/schemas/SuccessResponse' example: - $ref: http://foo.bar#/examples/address-example.json + $ref: http://foo.bar/other-api.yaml#/components/examples/successResponse ``` #### Reference Object