From 9f60a0a05416fccb8d7f0dd174c19d84c4843042 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.0.4.md | 230 +++++++++++++++++++++++----------------------- 1 file changed, 114 insertions(+), 116 deletions(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 065597492e..845b145f8e 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -641,7 +641,7 @@ components: in: header petstore_auth: type: oauth2 - flows: + flows: implicit: authorizationUrl: http://example.org/api/oauth/dialog scopes: @@ -694,7 +694,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": { @@ -816,7 +816,7 @@ get: '200': description: pet response content: - '*/*' : + '*/*': schema: type: array items: @@ -824,7 +824,7 @@ get: default: description: error payload content: - 'text/html': + text/html: schema: $ref: '#/components/schemas/ErrorModel' parameters: @@ -835,7 +835,7 @@ parameters: schema: type: array items: - type: string + type: string style: simple ``` @@ -888,7 +888,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "schema": { "type": "object", "properties": { - "name": { + "name": { "description": "Updated name of the pet", "type": "string" }, @@ -897,7 +897,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "type": "string" } }, - "required": ["status"] + "required": ["status"] } } } @@ -943,28 +943,28 @@ parameters: type: string requestBody: content: - 'application/x-www-form-urlencoded': + application/x-www-form-urlencoded: schema: properties: - name: - description: Updated name of the pet - type: string - status: - description: Updated status of the pet - type: string + name: + description: Updated name of the pet + type: string + status: + description: Updated status of the pet + type: string required: - status 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 @@ -1269,36 +1269,36 @@ A request body with a referenced model definition. "$ref": "#/components/schemas/User" }, "examples": { - "user" : { - "summary": "User Example", - "externalValue": "http://foo.bar/examples/user-example.json" - } + "user" : { + "summary": "User Example", + "externalValue": "http://foo.bar/examples/user-example.json" } + } }, "application/xml": { "schema": { "$ref": "#/components/schemas/User" }, "examples": { - "user" : { - "summary": "User example in XML", - "externalValue": "http://foo.bar/examples/user-example.xml" - } + "user" : { + "summary": "User example in XML", + "externalValue": "http://foo.bar/examples/user-example.xml" } + } }, "text/plain": { "examples": { "user" : { - "summary": "User example in Plain text", - "externalValue": "http://foo.bar/examples/user-example.txt" + "summary": "User example in Plain text", + "externalValue": "http://foo.bar/examples/user-example.txt" } - } + } }, "*/*": { "examples": { "user" : { - "summary": "User example in other format", - "externalValue": "http://foo.bar/examples/user-example.whatever" + "summary": "User example in other format", + "externalValue": "http://foo.bar/examples/user-example.whatever" } } } @@ -1308,31 +1308,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: 'http://foo.bar/examples/user-example.json' - 'application/xml': + externalValue: http://foo.bar/examples/user-example.json + application/xml: schema: $ref: '#/components/schemas/User' examples: user: summary: User Example in XML - externalValue: 'http://foo.bar/examples/user-example.xml' - 'text/plain': + externalValue: http://foo.bar/examples/user-example.xml + text/plain: examples: user: summary: User example in text plain format - externalValue: 'http://foo.bar/examples/user-example.txt' + externalValue: http://foo.bar/examples/user-example.txt '*/*': examples: - user: + user: summary: User example in other format - externalValue: 'http://foo.bar/examples/user-example.whatever' + externalValue: http://foo.bar/examples/user-example.whatever ``` A body parameter that is an array of string values: @@ -1383,32 +1383,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" } } } @@ -1416,7 +1415,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ``` ```yaml -application/json: +application/json: schema: $ref: "#/components/schemas/Pet" examples: @@ -1479,7 +1478,7 @@ requestBody: 'image/png': schema: type: string - format: binary + format: binary ``` To upload multiple files, a `multipart` media type MUST be used: @@ -1706,7 +1705,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' @@ -1754,9 +1753,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' @@ -1774,7 +1773,6 @@ Response with a string type: } } } - } ``` @@ -1890,7 +1888,7 @@ Content-Length: 187 "http://clientdomain.com/fast", "http://clientdomain.com/medium", "http://clientdomain.com/slow" - ] + ] } 201 Created @@ -1921,8 +1919,8 @@ myCallback: post: requestBody: description: Callback payload - content: - 'application/json': + content: + application/json: schema: $ref: '#/components/schemas/SomePayload' responses: @@ -1938,8 +1936,8 @@ transactionCallback: post: requestBody: description: Callback payload - content: - 'application/json': + content: + 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: 'http://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: 'http://foo.bar/examples/address-example.txt' + externalValue: http://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 [RFC 6901](https://tools.ietf.org/html/rfc6901), `char` from [RFC 7159](https://tools.ietf.org/html/rfc7159#section-7) and `token` from [RFC 7230](https://tools.ietf.org/html/rfc7230#section-3.2.6). @@ -2238,8 +2236,8 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```json { - "name": "pet", - "description": "Pets operations" + "name": "pet", + "description": "Pets operations" } ``` @@ -2268,7 +2266,7 @@ This object cannot be extended with additional properties and any properties add ```json { - "$ref": "#/components/schemas/Pet" + "$ref": "#/components/schemas/Pet" } ``` @@ -2676,7 +2674,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' @@ -2692,7 +2690,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' @@ -2764,12 +2762,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. @@ -2869,9 +2867,9 @@ Basic string property: ```json { - "animals": { - "type": "string" - } + "animals": { + "type": "string" + } } ``` @@ -2888,12 +2886,12 @@ Basic string array property ([`wrapped`](#xmlWrapped) is `false` by default): ```json { - "animals": { - "type": "array", - "items": { - "type": "string" - } + "animals": { + "type": "array", + "items": { + "type": "string" } + } } ``` @@ -3280,7 +3278,7 @@ bearerFormat: JWT ```yaml type: oauth2 -flows: +flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: @@ -3343,7 +3341,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```yaml type: oauth2 -flows: +flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: @@ -3354,7 +3352,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