From 77ed1e1e0aa56fa3e0c9d048de1899a891f72b70 Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Tue, 5 Nov 2024 13:27:59 -0800 Subject: [PATCH] more fixes - incorrect syntax in 132 create. --- aep/general/0133/aep.md.j2 | 37 +--- aep/general/oas.yaml | 443 +++++++++++++++++++++++++++++++++++++ 2 files changed, 451 insertions(+), 29 deletions(-) create mode 100644 aep/general/oas.yaml diff --git a/aep/general/0133/aep.md.j2 b/aep/general/0133/aep.md.j2 index 726b1172..e8d582cc 100644 --- a/aep/general/0133/aep.md.j2 +++ b/aep/general/0133/aep.md.j2 @@ -62,6 +62,7 @@ rpc CreateBook(CreateBookRequest) returns (Book) { {% tab oas %} **Note:** OAS guidance not yet written +{% sample '../oas.yaml', '$.paths./publishers/{publisher}/books.post' %} {% endtabs %} @@ -107,38 +108,13 @@ message CreateBookRequest { {% tab oas %} -**Note:** OAS guidance not yet written - -{% endtabs %} +- The request body **must** be the resource being created. -### Long-running create +{% sample '../oas.yaml', 'book:' %} -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: +{% sample '../oas.yaml', '$.paths./publishers/{publisher}/books.post.requestBody' %} -- 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 +- The request body **must** be the resource being created. {% endtabs %} @@ -191,6 +167,9 @@ publishers/012345678-abcd-cdef/books/12341234-5678-abcd {% tab oas %} **Note:** OAS guidance not yet written +{% sample '../oas.yaml', '$.paths./publishers/{publisher}/books.post.requestBody' %} + +- The `id` field **must** be a query parameter on the request. {% endtabs %} diff --git a/aep/general/oas.yaml b/aep/general/oas.yaml new file mode 100644 index 00000000..e44bc54a --- /dev/null +++ b/aep/general/oas.yaml @@ -0,0 +1,443 @@ +components: + schemas: + book: + properties: + author: + items: + type: object + type: array + edition: + format: int32 + type: integer + etag: + type: string + id: + readOnly: true + type: string + x-terraform-id: true + path: + readOnly: true + type: string + price: + format: float + type: number + published: + type: boolean + required: + - price + - published + type: object + x-aep-resource: + parents: + - publisher + patterns: + - /publishers/{publisher}/books/{book} + plural: books + singular: book + book-edition: + properties: + displayname: + type: string + id: + readOnly: true + type: string + x-terraform-id: true + path: + readOnly: true + type: string + required: + - displayname + type: object + x-aep-resource: + parents: + - book + patterns: + - /publishers/{publisher}/books/{book}/editions/{book-edition} + plural: book-editions + singular: book-edition + isbn: + properties: + id: + readOnly: true + type: string + x-terraform-id: true + path: + readOnly: true + type: string + type: object + x-aep-resource: + patterns: + - /isbns/{isbn} + plural: isbns + singular: isbn + publisher: + properties: + description: + type: string + etag: + type: string + id: + readOnly: true + type: string + x-terraform-id: true + path: + readOnly: true + type: string + type: object + x-aep-resource: + patterns: + - /publishers/{publisher} + plural: publishers + singular: publisher +info: + title: bookstore.example.com + version: version not set +openapi: 3.1.0 +paths: + /isbns: + post: + parameters: + - in: query + name: id + required: true + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/isbn' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/isbn' + description: Successful response + /isbns/{isbn}: + get: + parameters: + - in: path + name: isbn + required: true + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/isbn' + description: Successful response + /publishers: + get: + parameters: + - in: query + name: max_page_size + required: true + type: integer + - in: query + name: page_token + required: true + type: string + responses: + '200': + content: + application/json: + schema: + properties: + results: + items: + $ref: '#/components/schemas/publisher' + type: array + type: object + description: Successful response + post: + parameters: + - in: query + name: id + required: true + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/publisher' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/publisher' + description: Successful response + /publishers/{publisher}: + delete: + parameters: + - in: path + name: publisher + required: true + type: string + responses: + '200': + content: null + description: '' + get: + parameters: + - in: path + name: publisher + required: true + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/publisher' + description: Successful response + patch: + parameters: + - in: path + name: publisher + required: true + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/publisher' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/publisher' + description: Successful response + put: + parameters: + - in: path + name: publisher + required: true + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/publisher' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/publisher' + description: Successful response + /publishers/{publisher}/books: + get: + parameters: + - in: path + name: publisher + required: true + type: string + - in: query + name: max_page_size + required: true + type: integer + - in: query + name: page_token + required: true + type: string + responses: + '200': + content: + application/json: + schema: + properties: + results: + items: + $ref: '#/components/schemas/book' + type: array + unreachable: + items: + type: string + type: array + type: object + description: Successful response + post: + parameters: + - in: path + name: publisher + required: true + type: string + - in: query + name: id + required: true + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/book' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/book' + description: Successful response + /publishers/{publisher}/books/{book}: + delete: + parameters: + - in: path + name: publisher + required: true + type: string + - in: path + name: book + required: true + type: string + responses: + '200': + content: null + description: '' + get: + parameters: + - in: path + name: publisher + required: true + type: string + - in: path + name: book + required: true + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/book' + description: Successful response + patch: + parameters: + - in: path + name: publisher + required: true + type: string + - in: path + name: book + required: true + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/book' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/book' + description: Successful response + /publishers/{publisher}/books/{book}/editions: + get: + parameters: + - in: path + name: publisher + required: true + type: string + - in: path + name: book + required: true + type: string + - in: query + name: max_page_size + required: true + type: integer + - in: query + name: page_token + required: true + type: string + responses: + '200': + content: + application/json: + schema: + properties: + results: + items: + $ref: '#/components/schemas/book-edition' + type: array + type: object + description: Successful response + post: + parameters: + - in: path + name: publisher + required: true + type: string + - in: path + name: book + required: true + type: string + - in: query + name: id + required: true + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/book-edition' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/book-edition' + description: Successful response + /publishers/{publisher}/books/{book}/editions/{book-edition}: + delete: + parameters: + - in: path + name: publisher + required: true + type: string + - in: path + name: book + required: true + type: string + - in: path + name: book-edition + required: true + type: string + responses: + '200': + content: null + description: '' + get: + parameters: + - in: path + name: publisher + required: true + type: string + - in: path + name: book + required: true + type: string + - in: path + name: book-edition + required: true + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/book-edition' + description: Successful response +servers: + - url: http://localhost:8081