fix(133): add oas examples

Adding oas examples for create. This also tests out the pattern outlined in aep-dev#230 - adding a generated oas.yaml and use selective elements from it as an example, which looks to work pretty well. There is a blocker on aep-dev/site-generator#43 to allow for support from a json-path like structure to target sub-elements, but this will at least allow for selective guidance to be easily added.
toumorokoshi · Oct 22, 2024 · 141ccd3 · 141ccd3
1 parent 2257780
commit 141ccd3
Show file tree

Hide file tree

Showing 2 changed files with 246 additions and 40 deletions.
diff --git a/aep/general/0133/aep.md.j2 b/aep/general/0133/aep.md.j2
@@ -31,6 +31,9 @@ Create methods are specified using the following pattern:
     **should** be the only variable in the URI path.
   - The collection identifier (`books` in the above example) **must** be a
     literal string.
+- Some resources take longer to be created than is reasonable for a regular API
+  request. In this situation, the API should use a [long-running
+  operation](/long-running-operations).
 
 {% tab proto %}
 
@@ -64,7 +67,7 @@ rpc CreateBook(CreateBookRequest) returns (Book) {
 
 {% tab oas %}
 
-**Note:** OAS guidance not yet written
+{% sample '../oas.yaml', '/publishers/{publisher_id}/books:' %}
 
 {% endtabs %}
 
@@ -111,38 +114,9 @@ message CreateBookRequest {
 
 {% tab oas %}
 
-**Note:** OAS guidance not yet written
+- The request body **must** be the resource being created.
 
-{% endtabs %}
-
-### Long-running create
-
-Some resources take longer to create a resource than is reasonable for a
-regular API request. In this situation, the API **should** use a long-running
-operation (AEP-151) instead:
-
-- The response type **must** be set to the resource (what the return type would
-  be if the RPC was not long-running).
-
-{% tab proto %}
-
-```proto
-rpc CreateBook(CreateBookRequest) returns (aep.api.Operation) {
-  option (google.api.http) = {
-    post: "/v1/{parent=publishers/*}/books"
-  };
-  option (aep.api.operation_info) = {
-    response_type: "Book"
-    metadata_type: "OperationMetadata"
-  };
-}
-```
-
-- Both the `response_type` and `metadata_type` fields **must** be specified.
-
-{% tab oas %}
-
-**Note:** OAS guidance not yet written
+{% sample '../oas.yaml', 'book:' %}
 
 {% endtabs %}
 
@@ -172,10 +146,6 @@ publishers/lacroix/books/les-miserables
 publishers/012345678-abcd-cdef/books/12341234-5678-abcd
 ```
 
-- The `id` field **must** exist on the request message, not the resource
-  itself.
-  - The field **may** be required or optional. If it is required, it **should**
-    include the corresponding annotation.
 - The `path` field on the resource **must** be ignored.
 - The documentation **should** explain what the acceptable format is, and the
   format **should** follow the guidance for resource path formatting in
@@ -192,16 +162,17 @@ publishers/012345678-abcd-cdef/books/12341234-5678-abcd
   the RPC, with a value of `"parent,{resource},id"` if the resource being
   created is not a top-level resource, or with a value of `"{resource},id"` if
   the resource being created is a top-level resource.
+- The `id` field **must** exist on the request message, not the resource
+  itself.
+  - The field **may** be required or optional. If it is required, it **should**
+    include the corresponding annotation.
 
 {% tab oas %}
 
-**Note:** OAS guidance not yet written
+- The `id` is a query parameter on the request URI.
 
 {% endtabs %}
 
-**Note:** For REST APIs, the user-specified ID field, `id`, is provided as a
-query parameters on the request URI.
-
 ### Errors
 
 See [errors][], in particular [when to use PERMISSION_DENIED and NOT_FOUND

diff --git a/aep/general/oas.yaml b/aep/general/oas.yaml
@@ -0,0 +1,235 @@
+components:
+  schemas:
+    book:
+      properties:
+        author:
+          items:
+            type: object
+          type: array
+        edition:
+          format: int32
+          type: integer
+        id:
+          readOnly: true
+          type: string
+          x-terraform-id: true
+        isbn:
+          items:
+            type: string
+          type: array
+        path:
+          readOnly: true
+          type: string
+        price:
+          format: float
+          type: number
+        published:
+          type: boolean
+      required:
+        - isbn
+        - price
+        - published
+      type: object
+      x-aep-resource:
+        parents:
+          - publisher
+        patterns:
+          - /publishers/{publisher_id}/books/{book_id}
+        plural: books
+        singular: book
+    publisher:
+      properties:
+        description:
+          type: string
+        id:
+          readOnly: true
+          type: string
+          x-terraform-id: true
+        path:
+          readOnly: true
+          type: string
+      type: object
+      x-aep-resource:
+        patterns:
+          - /publishers/{publisher_id}
+        plural: publishers
+        singular: publisher
+info:
+  title: bookstore.example.com
+  version: version not set
+paths:
+  /publishers:
+    get:
+      parameters: []
+      responses:
+        '200':
+          schema:
+            items:
+              $ref: '#/components/schemas/publisher'
+    post:
+      parameters:
+        - in: body
+          name: body
+          schema:
+            $ref: '#/components/schemas/publisher'
+        - in: query
+          name: id
+          required: true
+          schema: {}
+          type: string
+      responses:
+        '200':
+          schema:
+            $ref: '#/components/schemas/publisher'
+  /publishers/{publisher_id}:
+    delete:
+      parameters:
+        - in: path
+          name: publisher_id
+          required: true
+          schema: {}
+          type: string
+      responses:
+        '200':
+          schema: {}
+    get:
+      parameters:
+        - in: path
+          name: publisher_id
+          required: true
+          schema: {}
+          type: string
+      responses:
+        '200':
+          schema:
+            $ref: '#/components/schemas/publisher'
+    patch:
+      parameters:
+        - in: path
+          name: publisher_id
+          required: true
+          schema: {}
+          type: string
+        - in: body
+          name: body
+          schema:
+            $ref: '#/components/schemas/publisher'
+      responses:
+        '200':
+          schema:
+            $ref: '#/components/schemas/publisher'
+    put:
+      parameters:
+        - in: body
+          name: body
+          schema:
+            $ref: '#/components/schemas/publisher'
+      responses:
+        '200':
+          schema:
+            $ref: '#/components/schemas/publisher'
+  /publishers/{publisher_id}/books:
+    get:
+      parameters:
+        - in: path
+          name: publisher_id
+          required: true
+          schema: {}
+          type: string
+      responses:
+        '200':
+          schema:
+            items:
+              $ref: '#/components/schemas/book'
+    post:
+      parameters:
+        - in: path
+          name: publisher_id
+          required: true
+          schema: {}
+          type: string
+        - in: body
+          name: body
+          schema:
+            $ref: '#/components/schemas/book'
+        - in: query
+          name: id
+          required: true
+          schema: {}
+          type: string
+      responses:
+        '200':
+          schema:
+            $ref: '#/components/schemas/book'
+  /publishers/{publisher_id}/books/{book_id}:
+    delete:
+      parameters:
+        - in: path
+          name: publisher_id
+          required: true
+          schema: {}
+          type: string
+        - in: path
+          name: book_id
+          required: true
+          schema: {}
+          type: string
+      responses:
+        '200':
+          schema: {}
+    get:
+      parameters:
+        - in: path
+          name: publisher_id
+          required: true
+          schema: {}
+          type: string
+        - in: path
+          name: book_id
+          required: true
+          schema: {}
+          type: string
+      responses:
+        '200':
+          schema:
+            $ref: '#/components/schemas/book'
+    patch:
+      parameters:
+        - in: path
+          name: publisher_id
+          required: true
+          schema: {}
+          type: string
+        - in: path
+          name: book_id
+          required: true
+          schema: {}
+          type: string
+        - in: body
+          name: body
+          schema:
+            $ref: '#/components/schemas/book'
+      responses:
+        '200':
+          schema:
+            $ref: '#/components/schemas/book'
+    put:
+      parameters:
+        - in: path
+          name: publisher_id
+          required: true
+          schema: {}
+          type: string
+        - in: body
+          name: body
+          schema:
+            $ref: '#/components/schemas/book'
+      responses:
+        '200':
+          schema:
+            $ref: '#/components/schemas/book'
+schemes:
+  - http
+servers:
+  - url: http://localhost:8081
+swagger: '2.0'