Complete the OpenAPI examples.

aip-dev · May 24, 2021 · ad7e185 · ad7e185
1 parent 046bd25
commit ad7e185
Show file tree

Hide file tree

Showing 2 changed files with 65 additions and 7 deletions.
diff --git a/aip/general/0162/aip.md.j2 b/aip/general/0162/aip.md.j2
@@ -108,7 +108,7 @@ Revision" custom operation:
 
 {% tab oas %}
 
-{% sample 'revisions.oas.yaml', '/publishers/{publisherId}/books/{bookId}:tagRevision' %}
+{% sample 'revisions.oas.yaml', '/publishers/{publisherId}/books/{bookId}@{revisionId}:tagRevision' %}
 
 {% endtabs %}
 
@@ -139,6 +139,10 @@ standard `List` operations (AIP-132):
 
 {% sample 'revisions.proto', 'rpc ListBookRevisions', 'message ListBookRevisionsRequest' %}
 
+{% tab oas %}
+
+{% sample 'revisions.oas.yaml', '/publishers/{publisherId}/books/{bookId}:listRevisions' %}
+
 {% endtabs %}
 
 While revision listing operations are mostly similar to standard `List`
@@ -202,6 +206,10 @@ on user request **should** handle this with a `Commit` custom operation:
 
 {% sample 'revisions.proto', 'rpc CommitBook', 'message CommitBookRequest' %}
 
+{% tab oas %}
+
+{% sample 'revisions.oas.yaml', '/publishers/{publisherId}/books/{bookId}:commit' %}
+
 {% endtabs %}
 
 - The operation **must** use the `POST` HTTP method.
@@ -222,6 +230,10 @@ operation:
 
 {% sample 'revisions.proto', 'rpc RollbackBook', 'message RollbackBookRequest' %}
 
+{% tab oas %}
+
+{% sample 'revisions.oas.yaml', '/publishers/{publisherId}/books/{bookId}:rollback' %}
+
 {% endtabs %}
 
 - The operation **must** use the `POST` HTTP method.
@@ -254,6 +266,10 @@ to `Delete` (AIP-135) operations:
 
 {% sample 'revisions.proto', 'rpc DeleteBookRevision', 'message DeleteBookRevisionRequest' %}
 
+{% tab oas %}
+
+{% sample 'revisions.oas.yaml', '/publishers/{publisherId}/books/{bookId}@{revisionId}:deleteRevision' %}
+
 {% endtabs %}
 
 - The request message **must** have a `id` field to identify the resource

diff --git a/aip/general/0162/revisions.oas.yaml b/aip/general/0162/revisions.oas.yaml
@@ -51,7 +51,7 @@ paths:
                     next page.
 
                     If this field is omitted, there are no subsequent pages.
-  /publishers/{publisherId}/books/{bookId}:tagRevision:
+  /publishers/{publisherId}/books/{bookId}@{revisionId}:tagRevision:
     post:
       operationId: tagBookRevision
       description: |
@@ -65,11 +65,6 @@ paths:
           application/json:
             description: Request structure for tagging a book revision.
             properties:
-              id:
-                type: string
-                description: |
-                  The ID of the book to be tagged, including the revision ID.
-                required: true
               tag:
                 type: string
                 description: |
@@ -83,6 +78,53 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Book'
+  /publishers/{publisherId}/books/{bookId}@{revisionId}:deleteRevision:
+    delete:
+      operationId: deleteBookRevision
+      description: Delete a single revision of this book.
+      responses:
+        200:
+          description: OK
+  /publishers/{publisherId}/books/{bookId}:commit:
+    post:
+      operationId: commitBook
+      description: Save a new, discrete revision snapshot of the given book.
+      responses:
+        200:
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Book'
+  /publishers/{publisherId}/books/{bookId}:rollback:
+    post:
+      operationId: rollbackBook
+      description: |
+        Rollback the primary revision of a book to a previous revision.
+
+        This creates a new revision, with a new revision ID, with the contents
+        of the provided revision, as the most recent revision in the sequence.
+      requestBody:
+        content:
+          application/json:
+            description: |
+              Request structure for rolling back a book to a previous revision.
+            properties:
+              revisionId:
+                type: string
+                description: |
+                  The revision ID to roll back to.
+                  It must be a revision of the same book.
+
+                  Example: c7cfa2a8
+                required: true
+      responses:
+        200:
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Book'
 components:
   schema:
     Book: