From 0a66966b338c5c133e5e63713220709f4d481c24 Mon Sep 17 00:00:00 2001
From: Jonathan Stoikovitch <jstoiko@users.noreply.github.com>
Date: Fri, 5 Jan 2018 11:42:09 -0800
Subject: [PATCH] Fixed some invalid examples

It is understood that most examples showcased in the OAS spec are snippets, not entire OAS documents. However some of those snippets would not be valid even if included in entire OAS documents. This PR is an attempt to fix some of those examples.

**List of changes**:
- added a `GeneralError` schema inside the `Components Object Example`
- split the `Example Object Example` into multiple examples
---
 versions/3.0.2.md | 121 ++++++++++++++++++++++++++++------------------
 1 file changed, 75 insertions(+), 46 deletions(-)

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'
 ```