OAS examples for standard methods

aep/general/0133/aep.md.j2

@@ -111,7 +111,18 @@ message CreateBookRequest {
 
 {% tab oas %}
 
-**Note:** OAS guidance not yet written
+{% sample 'create.oas.yaml', 'paths' %}
+
+- The `operationId` **must** begin with the word `create`. The remainder of the
+  `operationId` **should** be the singular form of the resource type's name.
+  `#/components/schemas/Book`. The response **must** reference a schema with a `x-aep-resource` extension.
+- The request and response content **must** be the resource itself. For example:
+  `#/components/schemas/Book`. The request and 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
+    `{resourceName}Id` (such as `bookId`), and path parameters representing the
+    ID of parent resources **must** end with `Id`.
 
 {% endtabs %}
 
@@ -142,7 +153,9 @@ rpc CreateBook(CreateBookRequest) returns (aep.api.Operation) {
 
 {% tab oas %}
 
-**Note:** OAS guidance not yet written
+{% sample 'create_operation.oas.yaml', 'paths' %}
+
+- The response must reference a OAS schema that follows [AEP-151](aep-151).
 
 {% endtabs %}
 
@@ -195,7 +208,7 @@ publishers/012345678-abcd-cdef/books/12341234-5678-abcd
 
 {% tab oas %}
 
-**Note:** OAS guidance not yet written
+- There should be a field on the request body called 'id'.
 
 {% endtabs %}
 
@@ -229,6 +242,7 @@ path and use it in references from other resources.
 [aep-121]: ./0121.md
 [aep-122]: ./0122.md
 [aep-123]: ./0123.md
+[aep-151]: ./0151.md
 [aep-155]: ./0155.md
 [aep-203]: ./0203.md
 [aep-210]: ./0210.md

aep/general/0133/create.oas.yaml

@@ -0,0 +1,67 @@
+---
+openapi: 3.0.3
+info:
+  title: Library
+  version: 1.0.0
+paths:
+  /publishers/{publisherId}/books/{bookId}:
+    parameters:
+      - name: publisherId
+        in: path
+        description: The publisher to list books for.
+        required: true
+        schema:
+          type: string
+      - name: bookId
+        in: path
+        description: The name of the book.
+        required: true
+        schema:
+          type: string
+    post:
+      operationId: createBook
+      description: Create a Book
+      requestBody:
+        description: The book that is being created.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Book'
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Book'
+components:
+  schemas:
+    Book:
+      x-aep-resource:
+        singular: book
+        plural: books
+        patterns:
+          - 'publishers/{publisher}/books/{book}'
+      description: A representation of a single book.
+      type: object
+      properties:
+        name:
+          type: string
+          description: |
+            The name of the book.
+            Format: publishers/{publisher}/books/{book}
+        isbn:
+          type: string
+          description: |
+            The ISBN (International Standard Book Number) for this book.
+        title:
+          type: string
+          description: The title of the book.
+        authors:
+          type: array
+          items:
+            type: string
+          description: The author or authors of the book.
+        rating:
+          type: number
+          description: The rating assigned to the book.

aep/general/0133/create_operation.oas.yaml

@@ -0,0 +1,101 @@
+---
+openapi: 3.0.3
+info:
+  title: Library
+  version: 1.0.0
+paths:
+  /publishers/{publisherId}/books/{bookId}:
+    parameters:
+      - name: publisherId
+        in: path
+        description: The publisher to list books for.
+        required: true
+        schema:
+          type: string
+      - name: bookId
+        in: path
+        description: The name of the book.
+        required: true
+        schema:
+          type: string
+    post:
+      operationId: createBook
+      description: Create a Book
+      requestBody:
+        description: The book that is being created.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Book'
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Operation'
+components:
+  schemas:
+    Operation:
+      description: The status of a long running operation.
+      properties:
+        path:
+          type: string
+          description:
+            The server-assigned path, which is only unique within the same
+            service that originally returns it.
+        done:
+          type: boolean
+          description: >-
+            If the value is false, it means the operation is still in progress.
+            If true, the operation is completed, and either response or error
+            is available.
+        error:
+          $ref: '#/components/schemas/Error'
+        metadata:
+          type: object
+          description: >-
+            Service-specific metadata associated with the operation. It
+            typically contains progress information and common metadata such as
+            create time. Some services might not provide such metadata. Any
+            method that returns a long-running operation should document the
+            metadata type, if any.
+        response:
+          type: object
+          description: >-
+            The normal response of the operation in case of success. Depending
+            on the method, this may be the empty object, the resource on which
+            the operation is performed, or a custom response.
+      required:
+        - path
+        - done
+
+    Book:
+      x-aep-resource:
+        singular: book
+        plural: books
+        patterns:
+          - 'publishers/{publisher}/books/{book}'
+      description: A representation of a single book.
+      type: object
+      properties:
+        name:
+          type: string
+          description: |
+            The name of the book.
+            Format: publishers/{publisher}/books/{book}
+        isbn:
+          type: string
+          description: |
+            The ISBN (International Standard Book Number) for this book.
+        title:
+          type: string
+          description: The title of the book.
+        authors:
+          type: array
+          items:
+            type: string
+          description: The author or authors of the book.
+        rating:
+          type: number
+          description: The rating assigned to the book.

aep/general/0134/aep.md.j2

@@ -266,7 +266,19 @@ message Book {
 
 {% tab oas %}
 
-**Note:** OAS example not yet written.
+{% sample 'update.oas.yaml', 'paths' %}
+
+- The `operationId` **must** begin with the word `update`. The remainder of the
+  `operationId` **should** be the singular form of the resource type's name.
+  `#/components/schemas/Book`. The response **must** reference a schema with a `x-aep-resource` extension.
+- The request and response content **must** be the resource itself. For example:
+  `#/components/schemas/Book`. The request and 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
+    `{resourceName}Id` (such as `bookId`), and path parameters representing the
+    ID of parent resources **must** end with `Id`.
+- If partial resource updates are allowed, the field `update_mask` must be included as a query parameter.
 
 {% endtabs %}
 

aep/general/0134/update.oas.yaml

@@ -0,0 +1,73 @@
+---
+openapi: 3.0.3
+info:
+  title: Library
+  version: 1.0.0
+paths:
+  /publishers/{publisherId}/books/{bookId}:
+    parameters:
+      - name: publisherId
+        in: path
+        description: The publisher to list books for.
+        required: true
+        schema:
+          type: string
+      - name: bookId
+        in: path
+        description: The name of the book.
+        required: true
+        schema:
+          type: string
+      - name: updateMask
+        in: query
+        description: The list of fields that should be updated.
+        required: false
+        schema:
+          type: string
+    patch:
+      operationId: updateBook
+      description: Update a Book
+      requestBody:
+        description: The book that is being updated.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Book'
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Book'
+components:
+  schemas:
+    Book:
+      x-aep-resource:
+        singular: book
+        plural: books
+        patterns:
+          - 'publishers/{publisher}/books/{book}'
+      description: A representation of a single book.
+      type: object
+      properties:
+        name:
+          type: string
+          description: |
+            The name of the book.
+            Format: publishers/{publisher}/books/{book}
+        isbn:
+          type: string
+          description: |
+            The ISBN (International Standard Book Number) for this book.
+        title:
+          type: string
+          description: The title of the book.
+        authors:
+          type: array
+          items:
+            type: string
+          description: The author or authors of the book.
+        rating:
+          type: number
+          description: The rating assigned to the book.