From 34c2dca8167d8830136dce533b0c4f48226d2528 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.1.1.md | 189 +++++++++++++++++++++++----------------------- 1 file changed, 94 insertions(+), 95 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index a2ab865860..dfe0c3f2ed 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.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": { @@ -818,7 +818,7 @@ get: '200': description: pet response content: - '*/*' : + */*: schema: type: array items: @@ -826,7 +826,7 @@ get: default: description: error payload content: - 'text/html': + text/html: schema: $ref: '#/components/schemas/ErrorModel' parameters: @@ -837,7 +837,7 @@ parameters: schema: type: array items: - type: string + type: string style: simple ``` @@ -890,7 +890,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "schema": { "type": "object", "properties": { - "name": { + "name": { "description": "Updated name of the pet", "type": "string" }, @@ -899,7 +899,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "type": "string" } }, - "required": ["status"] + "required": ["status"] } } } @@ -945,11 +945,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: @@ -960,14 +960,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 @@ -1272,36 +1272,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" } } } @@ -1311,29 +1311,29 @@ 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': + application/xml: schema: $ref: '#/components/schemas/User' examples: user: summary: User example in XML externalValue: 'https://foo.bar/examples/user-example.xml' - 'text/plain': + text/plain: examples: user: summary: User example in Plain text 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' ``` @@ -1387,32 +1387,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" } } } @@ -1420,7 +1419,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ``` ```yaml -application/json: +application/json: schema: $ref: "#/components/schemas/Pet" examples: @@ -1459,24 +1458,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. @@ -1705,7 +1704,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' @@ -1753,9 +1752,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' @@ -1773,7 +1772,6 @@ Response with a string type: } } } - } ``` @@ -1891,7 +1889,7 @@ Content-Length: 187 "https://clientdomain.com/fast", "https://clientdomain.com/medium", "https://clientdomain.com/slow" - ] + ] } 201 Created @@ -1923,7 +1921,7 @@ myCallback: requestBody: description: Callback payload content: - 'application/json': + application/json: schema: $ref: '#/components/schemas/SomePayload' responses: @@ -1940,7 +1938,7 @@ transactionCallback: requestBody: description: Callback payload content: - 'application/json': + application/json: schema: $ref: '#/components/schemas/SomePayload' responses: @@ -1974,21 +1972,21 @@ 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': + text/plain: examples: - textExample: + textExample: summary: This is a text example externalValue: 'https://foo.bar/examples/address-example.txt' ``` @@ -1997,13 +1995,13 @@ 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' ``` @@ -2013,7 +2011,7 @@ In a response: responses: '200': description: your car appointment has been booked - content: + content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' @@ -2061,7 +2059,7 @@ paths: - name: id in: path required: true - description: the user identifier, as userId + description: the user identifier, as userId schema: type: string get: @@ -2089,7 +2087,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 @@ -2155,22 +2153,23 @@ 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). @@ -2664,7 +2663,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' @@ -2680,7 +2679,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' @@ -3335,7 +3334,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```yaml type: oauth2 -flows: +flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: @@ -3346,7 +3345,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