diff --git a/versions/3.0.2.md b/versions/3.0.2.md index 0c46179866..dd42a82ee8 100644 --- a/versions/3.0.2.md +++ b/versions/3.0.2.md @@ -472,6 +472,18 @@ my.org.User ```json "components": { "schemas": { + "GeneralError": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + } + } + }, "Category": { "type": "object", "properties": { @@ -562,6 +574,14 @@ my.org.User ```yaml components: schemas: + GeneralError: + type: object + properties: + code: + type: integer + format: int32 + message: + type: string Category: type: object properties: @@ -1903,10 +1923,11 @@ In all cases, the example value is expected to be compatible with the type schem of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible. -##### Example Object Example +##### Example Object Examples + +In a model: ```yaml -# in a model schemas: properties: name: @@ -1914,54 +1935,62 @@ schemas: examples: name: $ref: http://example.org/petapi-examples/openapi.json#/components/examples/name-example +``` -# in a request body: - requestBody: - content: - 'application/json': - schema: - $ref: '#/components/schemas/Address' - examples: - foo: - summary: A foo example - value: {"foo": "bar"} - bar: - summary: A bar example - value: {"bar": "baz"} - 'application/xml': - examples: - xmlExample: - summary: This is an example in XML - externalValue: 'http://example.org/examples/address-example.xml' - 'text/plain': - examples: - textExample: - summary: This is a text example - externalValue: 'http://foo.bar/examples/address-example.txt' - +In a request body: -# in a parameter - parameters: - - name: 'zipCode' - in: 'query' +```yaml +requestBody: + content: + 'application/json': schema: - type: 'string' - format: 'zip-code' - examples: - zip-example: - $ref: '#/components/examples/zip-example' + $ref: '#/components/schemas/Address' + examples: + foo: + summary: A foo example + value: {"foo": "bar"} + bar: + summary: A bar example + value: {"bar": "baz"} + 'application/xml': + examples: + xmlExample: + summary: This is an example in XML + externalValue: 'http://example.org/examples/address-example.xml' + 'text/plain': + examples: + textExample: + summary: This is a text example + externalValue: 'http://foo.bar/examples/address-example.txt' +``` -# in a response - responses: - '200': - description: your car appointment has been booked - content: - application/json: - schema: - $ref: '#/components/schemas/SuccessResponse' - examples: - confirmation-success: - $ref: '#/components/examples/confirmation-success' +In a parameter: + +```yaml +parameters: + - name: 'zipCode' + in: 'query' + schema: + type: 'string' + format: 'zip-code' + examples: + zip-example: + $ref: '#/components/examples/zip-example' +``` + +In a response: + +```yaml +responses: + '200': + description: your car appointment has been booked + content: + application/json: + schema: + $ref: '#/components/schemas/SuccessResponse' + examples: + confirmation-success: + $ref: '#/components/examples/confirmation-success' ```