Add component mandate for OAS resources on GET (#212)

* Add additional guidance on GET

* prettier

* missing parameter

* change json to yaml

aep/general/0004/aep.md.j2

@@ -64,19 +64,25 @@ message Topic {
 
 {% tab oas %}
 
-For OpenAPI 3.0, use the `x-aep-resource` extension:
+For OpenAPI 3.0, Resources must be defined in `#components/schemas` and use the `x-aep-resource` extension:
 
 ```json
 {
-  "type": "object",
-  "x-aep-resource": {
-    "singular": "user-event",
-    "plural": "user-events",
-    "patterns": [
-      "projects/{project}/user-events/{user-event}",
-      "folder/{folder}/user-events/{user-event}",
-      "users/{user}/events/{user-event}"
-    ]
+  "components": {
+    "schemas": {
+      "UserEvent": {
+        "type": "object",
+        "x-aep-resource": {
+          "singular": "user-event",
+          "plural": "user-events",
+          "patterns": [
+            "projects/{project}/user-events/{user-event}",
+            "folder/{folder}/user-events/{user-event}",
+            "users/{user}/events/{user-event}"
+          ]
+        }
+      }
+    }
   }
 }
 ```

aep/general/0131/aep.md.j2

@@ -117,7 +117,7 @@ metadata:
 - The `operationId` **must** begin with the word `get`. The remainder of the
   `operationId` **should** be the singular form of the resource type's name.
 - The response content **must** be the resource itself. For example:
-  `#/components/schemas/Book`
+  `#/components/schemas/Book`. The response **must** reference a schema with a `x-aep-resource` extension.
 - The URI **should** contain a variable for each individual ID in the resource
   hierarchy.
   - The path parameter for all resource IDs **must** be in the form

aep/general/0131/get.oas.yaml

@@ -18,13 +18,23 @@ paths:
 components:
   schema:
     Book:
+      type: object
+      x-aep-resource:
+        singular: book
+        plural: books
+        patterns:
+          - 'publishers/{publisher}/books/{book}'
       description: A representation of a single book.
       properties:
         name:
           type: string
           description: |
             The name of the book.
             Format: publishers/{publisher}/books/{book}
+        publisher:
+          type: string
+          description: |
+            The name of the publisher.
         isbn:
           type: string
           description: |

aep/general/0141/aep.md.j2

@@ -1,4 +1,4 @@
-Quantities
+# Quantities
 
 Many services need to represent a discrete quantity of items (number of bytes,
 number of miles, number of nodes, etc.).