From 8045cffa30a558d6ed1454c56c8ee7b445125dcb Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Sun, 30 Oct 2022 16:26:57 -0500 Subject: [PATCH] Improve/fix oas examples --- aip/general/0135/aip.md.j2 | 3 +- aip/general/0135/cascading_delete.oas.yaml | 27 ++++++++++-- aip/general/0135/cascading_delete.proto | 2 +- aip/general/0135/delete.oas.yaml | 27 ++++++++++-- aip/general/0135/delete.proto | 2 +- aip/general/0135/delete_if_existing.oas.yaml | 27 ++++++++++-- aip/general/0135/delete_if_existing.proto | 2 +- aip/general/0135/lro_delete.oas.yaml | 46 +++++++++++++++++--- aip/general/0135/lro_delete.proto | 2 +- aip/general/0135/protected_delete.oas.yaml | 27 ++++++++++-- aip/general/0135/protected_delete.proto | 2 +- 11 files changed, 139 insertions(+), 28 deletions(-) diff --git a/aip/general/0135/aip.md.j2 b/aip/general/0135/aip.md.j2 index 3a295f0c..ce436f21 100644 --- 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 index 135be342..b1348f58 100644 --- 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 index fa6e890d..6c5cf079 100644 --- 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 index 32a8f997..26b809fe 100644 --- 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 index 1215df99..529215a9 100644 --- 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 index c502d8cb..43765103 100644 --- 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 index c8a7bdc2..2900d09f 100644 --- 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 index 65d36071..15c89412 100644 --- 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 \ No newline at end of file diff --git a/aip/general/0135/lro_delete.proto b/aip/general/0135/lro_delete.proto index d16b5aed..a1c3924d 100644 --- 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 index e5f75944..c486d4ed 100644 --- 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 index 44e2117b..397901aa 100644 --- 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/*}"