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

Author: jstoiko

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,65 +1923,74 @@ 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:
       type: string
       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'
 ```