From abaa97da26cbedc9fa0ff224f8484eeaa0c44dff Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Tue, 5 Dec 2023 20:40:57 -0800 Subject: [PATCH] whitespace and quoting fixes in json and yaml examples --- versions/3.2.0.md | 204 +++++++++++++++++++++++----------------------- 1 file changed, 101 insertions(+), 103 deletions(-) diff --git a/versions/3.2.0.md b/versions/3.2.0.md index 5deef0e452..45d59a7c3f 100644 --- a/versions/3.2.0.md +++ b/versions/3.2.0.md @@ -644,7 +644,7 @@ components: in: header petstore_auth: type: oauth2 - flows: + flows: implicit: authorizationUrl: https://example.org/api/oauth/dialog scopes: @@ -696,7 +696,7 @@ The following may lead to ambiguous resolution: "get": { "description": "Returns all pets from the system that the user has access to", "responses": { - "200": { + "200": { "description": "A list of pets.", "content": { "application/json": { @@ -817,7 +817,7 @@ get: '200': description: pet response content: - '*/*' : + '*/*': schema: type: array items: @@ -825,7 +825,7 @@ get: default: description: error payload content: - 'text/html': + text/html: schema: $ref: '#/components/schemas/ErrorModel' parameters: @@ -836,7 +836,7 @@ parameters: schema: type: array items: - type: string + type: string style: simple ``` @@ -889,7 +889,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "schema": { "type": "object", "properties": { - "name": { + "name": { "description": "Updated name of the pet", "type": "string" }, @@ -898,7 +898,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "type": "string" } }, - "required": ["status"] + "required": ["status"] } } } @@ -944,11 +944,11 @@ parameters: type: string requestBody: content: - 'application/x-www-form-urlencoded': + application/x-www-form-urlencoded: schema: type: object properties: - name: + name: description: Updated name of the pet type: string status: @@ -959,14 +959,14 @@ requestBody: responses: '200': description: Pet updated. - content: - 'application/json': {} - 'application/xml': {} + content: + application/json: {} + application/xml: {} '405': description: Method Not Allowed - content: - 'application/json': {} - 'application/xml': {} + content: + application/json: {} + application/xml: {} security: - petstore_auth: - write:pets @@ -1271,36 +1271,36 @@ A request body with a referenced model definition. "$ref": "#/components/schemas/User" }, "examples": { - "user" : { - "summary": "User Example", - "externalValue": "https://foo.bar/examples/user-example.json" - } + "user" : { + "summary": "User Example", + "externalValue": "https://foo.bar/examples/user-example.json" } + } }, "application/xml": { "schema": { "$ref": "#/components/schemas/User" }, "examples": { - "user" : { - "summary": "User example in XML", - "externalValue": "https://foo.bar/examples/user-example.xml" - } + "user" : { + "summary": "User example in XML", + "externalValue": "https://foo.bar/examples/user-example.xml" } + } }, "text/plain": { "examples": { "user" : { - "summary": "User example in Plain text", - "externalValue": "https://foo.bar/examples/user-example.txt" + "summary": "User example in Plain text", + "externalValue": "https://foo.bar/examples/user-example.txt" } - } + } }, "*/*": { "examples": { "user" : { - "summary": "User example in other format", - "externalValue": "https://foo.bar/examples/user-example.whatever" + "summary": "User example in other format", + "externalValue": "https://foo.bar/examples/user-example.whatever" } } } @@ -1310,31 +1310,31 @@ A request body with a referenced model definition. ```yaml description: user to add to the system -content: - 'application/json': +content: + application/json: schema: $ref: '#/components/schemas/User' examples: user: summary: User Example - externalValue: 'https://foo.bar/examples/user-example.json' - 'application/xml': + externalValue: https://foo.bar/examples/user-example.json + application/xml: schema: $ref: '#/components/schemas/User' examples: user: summary: User example in XML - externalValue: 'https://foo.bar/examples/user-example.xml' - 'text/plain': + externalValue: https://foo.bar/examples/user-example.xml + text/plain: examples: user: summary: User example in Plain text - externalValue: 'https://foo.bar/examples/user-example.txt' + externalValue: https://foo.bar/examples/user-example.txt '*/*': examples: - user: + user: summary: User example in other format - externalValue: 'https://foo.bar/examples/user-example.whatever' + externalValue: https://foo.bar/examples/user-example.whatever ``` A body parameter that is an array of string values: @@ -1386,32 +1386,31 @@ This object MAY be extended with [Specification Extensions](#specificationExtens { "application/json": { "schema": { - "$ref": "#/components/schemas/Pet" + "$ref": "#/components/schemas/Pet" }, "examples": { "cat" : { "summary": "An example of a cat", - "value": - { - "name": "Fluffy", - "petType": "Cat", - "color": "White", - "gender": "male", - "breed": "Persian" - } + "value": { + "name": "Fluffy", + "petType": "Cat", + "color": "White", + "gender": "male", + "breed": "Persian" + } }, "dog": { "summary": "An example of a dog with a cat's name", - "value" : { + "value" : { "name": "Puma", "petType": "Dog", "color": "Black", "gender": "Female", "breed": "Mixed" - }, - "frog": { - "$ref": "#/components/examples/frog-example" } + }, + "frog": { + "$ref": "#/components/examples/frog-example" } } } @@ -1419,7 +1418,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ``` ```yaml -application/json: +application/json: schema: $ref: "#/components/schemas/Pet" examples: @@ -1458,24 +1457,24 @@ Content transferred in binary (octet-stream) MAY omit `schema`: ```yaml # a PNG image as a binary file: content: - image/png: {} + image/png: {} ``` ```yaml # an arbitrary binary file: content: - application/octet-stream: {} + application/octet-stream: {} ``` Binary content transferred with base64 encoding: ```yaml content: - image/png: - schema: - type: string - contentMediaType: image/png - contentEncoding: base64 + image/png: + schema: + type: string + contentMediaType: image/png + contentEncoding: base64 ``` Note that the `Content-Type` remains `image/png`, describing the semantics of the payload. The JSON Schema `type` and `contentEncoding` fields explain that the payload is transferred as text. The JSON Schema `contentMediaType` is technically redundant, but can be used by JSON Schema tools that may not be aware of the OpenAPI context. @@ -1704,7 +1703,7 @@ A 200 response for a successful operation and a default response for others (imp ```yaml '200': description: a pet to be returned - content: + content: application/json: schema: $ref: '#/components/schemas/Pet' @@ -1752,9 +1751,9 @@ Response of an array of a complex type: ```yaml description: A complex object array response -content: +content: application/json: - schema: + schema: type: array items: $ref: '#/components/schemas/VeryComplexType' @@ -1772,7 +1771,6 @@ Response with a string type: } } } - } ``` @@ -1890,7 +1888,7 @@ Content-Length: 187 "https://clientdomain.com/fast", "https://clientdomain.com/medium", "https://clientdomain.com/slow" - ] + ] } 201 Created @@ -1922,7 +1920,7 @@ myCallback: requestBody: description: Callback payload content: - 'application/json': + application/json: schema: $ref: '#/components/schemas/SomePayload' responses: @@ -1939,7 +1937,7 @@ transactionCallback: requestBody: description: Callback payload content: - 'application/json': + application/json: schema: $ref: '#/components/schemas/SomePayload' responses: @@ -1973,36 +1971,36 @@ requestBody: 'application/json': schema: $ref: '#/components/schemas/Address' - examples: + examples: foo: summary: A foo example value: {"foo": "bar"} bar: summary: A bar example value: {"bar": "baz"} - 'application/xml': - examples: + application/xml: + examples: xmlExample: summary: This is an example in XML - externalValue: 'https://example.org/examples/address-example.xml' - 'text/plain': + externalValue: https://example.org/examples/address-example.xml + text/plain: examples: - textExample: + textExample: summary: This is a text example - externalValue: 'https://foo.bar/examples/address-example.txt' + externalValue: https://foo.bar/examples/address-example.txt ``` In a parameter: ```yaml parameters: - - name: 'zipCode' - in: 'query' + - name: zipCode + in: query schema: - type: 'string' - format: 'zip-code' + type: string + format: zip-code examples: - zip-example: + zip-example: $ref: '#/components/examples/zip-example' ``` @@ -2012,7 +2010,7 @@ In a response: responses: '200': description: your car appointment has been booked - content: + content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' @@ -2060,7 +2058,7 @@ paths: - name: id in: path required: true - description: the user identifier, as userId + description: the user identifier, as userId schema: type: string get: @@ -2088,7 +2086,7 @@ paths: - name: userid in: path required: true - description: the user identifier, as userId + description: the user identifier, as userId schema: type: string # linked operation @@ -2137,7 +2135,7 @@ or an absolute `operationRef`: links: UserRepositories: # returns array of '#/components/schemas/repository' - operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get' + operationRef: https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get parameters: username: $response.body#/username ``` @@ -2154,22 +2152,22 @@ This mechanism is used by [Link Objects](#linkObject) and [Callback Objects](#ca The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax ```abnf - expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source ) - source = ( header-reference / query-reference / path-reference / body-reference ) - header-reference = "header." token - query-reference = "query." name - path-reference = "path." name - body-reference = "body" ["#" json-pointer ] - json-pointer = *( "/" reference-token ) - reference-token = *( unescaped / escaped ) - unescaped = %x00-2E / %x30-7D / %x7F-10FFFF - ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped' - escaped = "~" ( "0" / "1" ) - ; representing '~' and '/', respectively - name = *( CHAR ) - token = 1*tchar - tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / - "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA + expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source ) + source = ( header-reference / query-reference / path-reference / body-reference ) + header-reference = "header." token + query-reference = "query." name + path-reference = "path." name + body-reference = "body" ["#" json-pointer ] + json-pointer = *( "/" reference-token ) + reference-token = *( unescaped / escaped ) + unescaped = %x00-2E / %x30-7D / %x7F-10FFFF + ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped' + escaped = "~" ( "0" / "1" ) + ; representing '~' and '/', respectively + name = *( CHAR ) + token = 1*tchar + tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / + "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA ``` Here, `json-pointer` is taken from [RFC6901](https://tools.ietf.org/html/rfc6901), `char` from [RFC7159](https://tools.ietf.org/html/rfc7159#section-7) and `token` from [RFC7230](https://tools.ietf.org/html/rfc7230#section-3.2.6). @@ -2663,7 +2661,7 @@ components: required: - name - petType - Cat: ## "Cat" will be used as the discriminator value + Cat: # "Cat" will be used as the discriminator value description: A representation of a cat allOf: - $ref: '#/components/schemas/Pet' @@ -2679,7 +2677,7 @@ components: - aggressive required: - huntingSkill - Dog: ## "Dog" will be used as the discriminator value + Dog: # "Dog" will be used as the discriminator value description: A representation of a dog allOf: - $ref: '#/components/schemas/Pet' @@ -2753,12 +2751,12 @@ MyResponseType: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' - - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json' + - $ref: https://gigantic-server.com/schemas/Monster/schema.json discriminator: propertyName: petType mapping: dog: '#/components/schemas/Dog' - monster: 'https://gigantic-server.com/schemas/Monster/schema.json' + monster: https://gigantic-server.com/schemas/Monster/schema.json ``` Here the discriminator _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `Dog`. If the discriminator _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison. @@ -3337,7 +3335,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```yaml type: oauth2 -flows: +flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: @@ -3348,7 +3346,7 @@ flows: tokenUrl: https://example.com/api/oauth/token scopes: write:pets: modify pets in your account - read:pets: read your pets + read:pets: read your pets ``` #### Security Requirement Object