Improve/fix oas examples

aip-dev · Oct 30, 2022 · 8045cff · 8045cff
1 parent f7ce6bf
commit 8045cff
Show file tree

Hide file tree

Showing 11 changed files with 139 additions and 28 deletions.
diff --git a/aip/general/0135/aip.md.j2 b/aip/general/0135/aip.md.j2
@@ -33,7 +33,7 @@ Accept: application/json
   **should not** include optional fields in the query string unless described
   in another AIP.
 - Single-resource `DELETE` operations **must** return `204 No Content` with no
-  response.
+  response body.
   - Exception: If the resource is soft deleted (AIP-164), in which case the
     operation **must** return `200 OK` and the resource itself, without any
     additional wrapping.
@@ -51,7 +51,6 @@ Accept: application/json
   - If the delete RPC is [long-running](#long-running-delete), the response
     message **must** be a `google.longrunning.Operation` which resolves to the
     correct response.
-- The HTTP method **must** be `DELETE`.
 - The request message field receiving the resource name **should** map to the
   URI path.
   - This field **should** be called `name`.

diff --git a/aip/general/0135/cascading_delete.oas.yaml b/aip/general/0135/cascading_delete.oas.yaml
@@ -5,6 +5,9 @@ info:
   version: 1.0.0
 paths:
   /publishers/{publisherId}/books/{bookId}:
+    parameters:
+    - $ref: "#/components/parameters/PublisherId"
+    - $ref: "#/components/parameters/BookId"
     delete:
       operationId: deleteBook
       description: Delete a single book.
@@ -17,10 +20,25 @@ paths:
             If set to true, any books from this publisher will also be deleted.
             (Otherwise, the request fails unless the publisher has no books.)
       responses:
-        204:
-          description: No Content
+        '204':
+          description: Book was deleted
 components:
-  schema:
+  parameters:
+    PublisherId:
+      name: publisherId
+      in: path
+      description: The id of the book publisher.
+      required: true
+      schema:
+        type: string
+    BookId:
+      name: bookId
+      in: path
+      description: The id of the book.
+      required: true
+      schema:
+        type: string
+  schemas:
     Book:
       description: A representation of a single book.
       properties:
@@ -42,5 +60,6 @@ components:
             type: string
           description: The author or authors of the book.
         rating:
-          type: float
+          type: number
+          format: float32
           description: The rating assigned to the book.
diff --git a/aip/general/0135/cascading_delete.proto b/aip/general/0135/cascading_delete.proto
@@ -21,7 +21,7 @@ import "google/api/resource.proto";
 import "google/protobuf/empty.proto";
 
 service Library {
-  // Get a single book.
+  // Delete a single book.
   rpc DeletePublisher(DeletePublisherRequest) returns (google.protobuf.Empty) {
     option (google.api.http) = {
       delete: "/v1/{name=publishers/*}"

diff --git a/aip/general/0135/delete.oas.yaml b/aip/general/0135/delete.oas.yaml
@@ -5,14 +5,32 @@ info:
   version: 1.0.0
 paths:
   /publishers/{publisherId}/books/{bookId}:
+    parameters:
+    - $ref: "#/components/parameters/PublisherId"
+    - $ref: "#/components/parameters/BookId"
     delete:
       operationId: deleteBook
       description: Delete a single book.
       responses:
-        204:
-          description: No Content
+        '204':
+          description: Book was deleted
 components:
-  schema:
+  parameters:
+    PublisherId:
+      name: publisherId
+      in: path
+      description: The id of the book publisher.
+      required: true
+      schema:
+        type: string
+    BookId:
+      name: bookId
+      in: path
+      description: The id of the book.
+      required: true
+      schema:
+        type: string
+  schemas:
     Book:
       description: A representation of a single book.
       properties:
@@ -34,5 +52,6 @@ components:
             type: string
           description: The author or authors of the book.
         rating:
-          type: float
+          type: number
+          format: float32
           description: The rating assigned to the book.
diff --git a/aip/general/0135/delete.proto b/aip/general/0135/delete.proto
@@ -21,7 +21,7 @@ import "google/api/resource.proto";
 import "google/protobuf/empty.proto";
 
 service Library {
-  // Get a single book.
+  // Delete a single book.
   rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {
     option (google.api.http) = {
       delete: "/v1/{name=publishers/*/books/*}"

diff --git a/aip/general/0135/delete_if_existing.oas.yaml b/aip/general/0135/delete_if_existing.oas.yaml
@@ -5,6 +5,9 @@ info:
   version: 1.0.0
 paths:
   /publishers/{publisherId}/books/{bookId}:
+    parameters:
+    - $ref: "#/components/parameters/PublisherId"
+    - $ref: "#/components/parameters/BookId"
     delete:
       operationId: deleteBook
       description: Delete a single book.
@@ -17,10 +20,25 @@ paths:
             If set to true, and the book is not found, the request will succeed
             but no action will be taken on the server
       responses:
-        204:
-          description: No Content
+        '204':
+          description: Book was deleted
 components:
-  schema:
+  parameters:
+    PublisherId:
+      name: publisherId
+      in: path
+      description: The id of the book publisher.
+      required: true
+      schema:
+        type: string
+    BookId:
+      name: bookId
+      in: path
+      description: The id of the book.
+      required: true
+      schema:
+        type: string
+  schemas:
     Book:
       description: A representation of a single book.
       properties:
@@ -42,5 +60,6 @@ components:
             type: string
           description: The author or authors of the book.
         rating:
-          type: float
+          type: number
+          format: float32
           description: The rating assigned to the book.
diff --git a/aip/general/0135/delete_if_existing.proto b/aip/general/0135/delete_if_existing.proto
@@ -21,7 +21,7 @@ import "google/api/resource.proto";
 import "google/protobuf/empty.proto";
 
 service Library {
-  // Get a single book.
+  // Delete a single book.
   rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {
     option (google.api.http) = {
       delete: "/v1/{name=publishers/*/books/*}"

diff --git a/aip/general/0135/lro_delete.oas.yaml b/aip/general/0135/lro_delete.oas.yaml
@@ -5,18 +5,36 @@ info:
   version: 1.0.0
 paths:
   /publishers/{publisherId}/books/{bookId}:
+    parameters:
+    - $ref: "#/components/parameters/PublisherId"
+    - $ref: "#/components/parameters/BookId"
     delete:
       operationId: deleteBook
       description: Delete a single book.
       responses:
-        202:
+        '202':
           description: Accepted
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/DeleteBookStatus'
 components:
-  schema:
+  parameters:
+    PublisherId:
+      name: publisherId
+      in: path
+      description: The id of the book publisher.
+      required: true
+      schema:
+        type: string
+    BookId:
+      name: bookId
+      in: path
+      description: The id of the book.
+      required: true
+      schema:
+        type: string
+  schemas:
     Book:
       description: A representation of a single book.
       properties:
@@ -38,7 +56,8 @@ components:
             type: string
           description: The author or authors of the book.
         rating:
-          type: float
+          type: number
+          format: float32
           description: The rating assigned to the book.
     DeleteBookStatus:
       description: The status of the deleteBook operation.
@@ -52,11 +71,11 @@ components:
             metadata:
               type: object
               properties:
-                start_time:
+                startTime:
                   type: string
                   format: date-time
                   description: The time the operation started.
-                progress_percent:
+                progressPercent:
                   type: integer
                   format: int32
                   description: The current progress, expressed as an integer.
@@ -69,3 +88,20 @@ components:
                     - CANCELLING
                     - CANCELLED
                     - FAILED
+    StatusMonitor:
+      description: The status of a long running operation.
+      type: object
+      properties:
+        name:
+          type: string
+          description: The server-assigned name, 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'
+      required:
+        - name
+        - done
diff --git a/aip/general/0135/lro_delete.proto b/aip/general/0135/lro_delete.proto
@@ -21,7 +21,7 @@ import "google/api/resource.proto";
 import "google/longrunning/operations.proto";
 
 service Library {
-  // Get a single book.
+  // Delete a single book.
   rpc DeleteBook(DeleteBookRequest) returns (google.longrunning.Operation) {
     option (google.api.http) = {
       delete: "/v1/{name=publishers/*/books/*}"

diff --git a/aip/general/0135/protected_delete.oas.yaml b/aip/general/0135/protected_delete.oas.yaml
@@ -5,6 +5,9 @@ info:
   version: 1.0.0
 paths:
   /publishers/{publisherId}/books/{bookId}:
+    parameters:
+    - $ref: "#/components/parameters/PublisherId"
+    - $ref: "#/components/parameters/BookId"
     delete:
       operationId: deleteBook
       description: Delete a single book.
@@ -17,10 +20,25 @@ paths:
             The etag of the book.
             If this is provided, it must match the server's etag.
       responses:
-        204:
-          description: No Content
+        '204':
+          description: Book was deleted
 components:
-  schema:
+  parameters:
+    PublisherId:
+      name: publisherId
+      in: path
+      description: The id of the book publisher.
+      required: true
+      schema:
+        type: string
+    BookId:
+      name: bookId
+      in: path
+      description: The id of the book.
+      required: true
+      schema:
+        type: string
+  schemas:
     Book:
       description: A representation of a single book.
       properties:
@@ -42,5 +60,6 @@ components:
             type: string
           description: The author or authors of the book.
         rating:
-          type: float
+          type: number
+          format: float32
           description: The rating assigned to the book.
diff --git a/aip/general/0135/protected_delete.proto b/aip/general/0135/protected_delete.proto
@@ -21,7 +21,7 @@ import "google/api/resource.proto";
 import "google/protobuf/empty.proto";
 
 service Library {
-  // Get a single book.
+  // Delete a single book.
   rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {
     option (google.api.http) = {
       delete: "/v1/{name=publishers/*/books/*}"