diff --git a/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi.yaml b/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi.yaml index 475f60ec..eccd6cec 100644 --- a/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi.yaml +++ b/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi.yaml @@ -45,6 +45,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ListShelvesResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - LibraryService @@ -63,6 +69,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}: get: tags: @@ -83,6 +95,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' delete: tags: - LibraryService @@ -99,6 +117,12 @@ paths: "200": description: OK content: {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}/books: get: tags: @@ -133,6 +157,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ListBooksResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - LibraryService @@ -158,6 +188,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}/books/{book}: get: tags: @@ -184,6 +220,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' put: tags: - LibraryService @@ -222,6 +264,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' delete: tags: - LibraryService @@ -244,6 +292,12 @@ paths: "200": description: OK content: {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}/books/{book}:move: post: tags: @@ -278,6 +332,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}:merge: post: tags: @@ -311,6 +371,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: Book: @@ -346,6 +412,14 @@ components: description: The last update date and time. format: date-time description: A single book in the library. + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. ListBooksResponse: type: object properties: @@ -423,5 +497,21 @@ components: description: The last update date and time. format: date-time description: A Shelf contains a collection of books with a theme. + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: LibraryService diff --git a/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_default_response.yaml b/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_default_response.yaml new file mode 100644 index 00000000..17c57021 --- /dev/null +++ b/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_default_response.yaml @@ -0,0 +1,517 @@ +# Generated with protoc-gen-openapi +# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi + +openapi: 3.0.3 +info: + title: LibraryService API + description: |- + This API represents a simple digital library. It lets you manage Shelf + resources and Book resources in the library. It defines the following + resource model: + + - The API has a collection of [Shelf][google.example.library.v1.Shelf] + resources, named `shelves/*` + + - Each Shelf has a collection of [Book][google.example.library.v1.Book] + resources, named `shelves/*/books/*` + version: 0.0.1 +servers: + - url: https://library-example.googleapis.com +paths: + /v1/shelves: + get: + tags: + - LibraryService + description: |- + Lists shelves. The order is unspecified but deterministic. Newly created + shelves will not necessarily be added to the end of this list. + operationId: LibraryService_ListShelves + parameters: + - name: pageSize + in: query + description: Requested page size. Server may return fewer shelves than requested. If unspecified, server will pick an appropriate default. + schema: + type: integer + format: int32 + - name: pageToken + in: query + description: A token identifying a page of results the server should return. Typically, this is the value of [ListShelvesResponse.next_page_token][google.example.library.v1.ListShelvesResponse.next_page_token] returned from the previous call to `ListShelves` method. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListShelvesResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - LibraryService + description: Creates a shelf, and returns the new Shelf. + operationId: LibraryService_CreateShelf + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Shelf' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v1/shelves/{shelf}: + get: + tags: + - LibraryService + description: Gets a shelf. Returns NOT_FOUND if the shelf does not exist. + operationId: LibraryService_GetShelf + parameters: + - name: shelf + in: path + description: The shelf id. + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + delete: + tags: + - LibraryService + description: Deletes a shelf. Returns NOT_FOUND if the shelf does not exist. + operationId: LibraryService_DeleteShelf + parameters: + - name: shelf + in: path + description: The shelf id. + required: true + schema: + type: string + responses: + "200": + description: OK + content: {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v1/shelves/{shelf}/books: + get: + tags: + - LibraryService + description: |- + Lists books in a shelf. The order is unspecified but deterministic. Newly + created books will not necessarily be added to the end of this list. + Returns NOT_FOUND if the shelf does not exist. + operationId: LibraryService_ListBooks + parameters: + - name: shelf + in: path + description: The shelf id. + required: true + schema: + type: string + - name: pageSize + in: query + description: Requested page size. Server may return fewer books than requested. If unspecified, server will pick an appropriate default. + schema: + type: integer + format: int32 + - name: pageToken + in: query + description: A token identifying a page of results the server should return. Typically, this is the value of [ListBooksResponse.next_page_token][google.example.library.v1.ListBooksResponse.next_page_token]. returned from the previous call to `ListBooks` method. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListBooksResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - LibraryService + description: Creates a book, and returns the new Book. + operationId: LibraryService_CreateBook + parameters: + - name: shelf + in: path + description: The shelf id. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Book' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v1/shelves/{shelf}/books/{book}: + get: + tags: + - LibraryService + description: Gets a book. Returns NOT_FOUND if the book does not exist. + operationId: LibraryService_GetBook + parameters: + - name: shelf + in: path + description: The shelf id. + required: true + schema: + type: string + - name: book + in: path + description: The book id. + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + put: + tags: + - LibraryService + description: |- + Updates a book. Returns INVALID_ARGUMENT if the name of the book + is non-empty and does not equal the existing name. + operationId: LibraryService_UpdateBook + parameters: + - name: shelf + in: path + description: The shelf id. + required: true + schema: + type: string + - name: book + in: path + description: The book id. + required: true + schema: + type: string + - name: name + in: query + description: The name of the book to update. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Book' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + delete: + tags: + - LibraryService + description: Deletes a book. Returns NOT_FOUND if the book does not exist. + operationId: LibraryService_DeleteBook + parameters: + - name: shelf + in: path + description: The shelf id. + required: true + schema: + type: string + - name: book + in: path + description: The book id. + required: true + schema: + type: string + responses: + "200": + description: OK + content: {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v1/shelves/{shelf}/books/{book}:move: + post: + tags: + - LibraryService + description: |- + Moves a book to another shelf, and returns the new book. The book + id of the new book may not be the same as the original book. + operationId: LibraryService_MoveBook + parameters: + - name: shelf + in: path + description: The shelf id. + required: true + schema: + type: string + - name: book + in: path + description: The book id. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/MoveBookRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v1/shelves/{shelf}:merge: + post: + tags: + - LibraryService + description: |- + Merges two shelves by adding all books from the shelf named + `other_shelf_name` to shelf `name`, and deletes + `other_shelf_name`. Returns the updated shelf. + The book ids of the moved books may not be the same as the original books. + + Returns NOT_FOUND if either shelf does not exist. + This call is a no-op if the specified shelves are the same. + operationId: LibraryService_MergeShelves + parameters: + - name: shelf + in: path + description: The shelf id. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/MergeShelvesRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' +components: + schemas: + Book: + required: + - name + type: object + properties: + name: + type: string + description: The resource name of the book. Book names have the form `shelves/{shelf_id}/books/{book_id}`. The name is ignored when creating a book. + author: + type: string + description: The name of the book author. + title: + type: string + description: The title of the book. + read: + type: boolean + description: Value indicating whether the book has been read. + borrowTime: + readOnly: true + type: string + description: The previous borrowing timestamp. + format: RFC3339 + createdAt: + readOnly: true + type: string + description: The creation date and time. + format: date-time + updatedAt: + readOnly: true + type: string + description: The last update date and time. + format: date-time + description: A single book in the library. + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + ListBooksResponse: + type: object + properties: + books: + type: array + items: + $ref: '#/components/schemas/Book' + description: The list of books. + nextPageToken: + type: string + description: A token to retrieve next page of results. Pass this value in the [ListBooksRequest.page_token][google.example.library.v1.ListBooksRequest.page_token] field in the subsequent call to `ListBooks` method to retrieve the next page of results. + description: Response message for LibraryService.ListBooks. + ListShelvesResponse: + type: object + properties: + shelves: + type: array + items: + $ref: '#/components/schemas/Shelf' + description: The list of shelves. + nextPageToken: + type: string + description: A token to retrieve next page of results. Pass this value in the [ListShelvesRequest.page_token][google.example.library.v1.ListShelvesRequest.page_token] field in the subsequent call to `ListShelves` method to retrieve the next page of results. + description: Response message for LibraryService.ListShelves. + MergeShelvesRequest: + required: + - name + - otherShelfName + type: object + properties: + name: + type: string + description: The name of the shelf we're adding books to. + otherShelfName: + type: string + description: The name of the shelf we're removing books from and deleting. + description: Describes the shelf being removed (other_shelf_name) and updated (name) in this merge. + MoveBookRequest: + required: + - name + - otherShelfName + type: object + properties: + name: + type: string + description: The name of the book to move. + otherShelfName: + type: string + description: The name of the destination shelf. + description: Describes what book to move (name) and what shelf we're moving it to (other_shelf_name). + Shelf: + required: + - name + type: object + properties: + name: + type: string + description: The resource name of the shelf. Shelf names have the form `shelves/{shelf_id}`. The name is ignored when creating a shelf. + theme: + type: string + description: The theme of the shelf + nextSortAt: + readOnly: true + type: string + description: The next sorting date. + format: date + createdAt: + readOnly: true + type: string + description: The creation date and time. + format: date-time + updatedAt: + readOnly: true + type: string + description: The last update date and time. + format: date-time + description: A Shelf contains a collection of books with a theme. + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' +tags: + - name: LibraryService diff --git a/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_fq_schema_naming.yaml b/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_fq_schema_naming.yaml index 92ebd2f9..61c07f03 100644 --- a/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_fq_schema_naming.yaml +++ b/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_fq_schema_naming.yaml @@ -45,6 +45,12 @@ paths: application/json: schema: $ref: '#/components/schemas/google.example.library.v1.ListShelvesResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' post: tags: - LibraryService @@ -63,6 +69,12 @@ paths: application/json: schema: $ref: '#/components/schemas/google.example.library.v1.Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' /v1/shelves/{shelf}: get: tags: @@ -83,6 +95,12 @@ paths: application/json: schema: $ref: '#/components/schemas/google.example.library.v1.Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' delete: tags: - LibraryService @@ -99,6 +117,12 @@ paths: "200": description: OK content: {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' /v1/shelves/{shelf}/books: get: tags: @@ -133,6 +157,12 @@ paths: application/json: schema: $ref: '#/components/schemas/google.example.library.v1.ListBooksResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' post: tags: - LibraryService @@ -158,6 +188,12 @@ paths: application/json: schema: $ref: '#/components/schemas/google.example.library.v1.Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' /v1/shelves/{shelf}/books/{book}: get: tags: @@ -184,6 +220,12 @@ paths: application/json: schema: $ref: '#/components/schemas/google.example.library.v1.Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' put: tags: - LibraryService @@ -222,6 +264,12 @@ paths: application/json: schema: $ref: '#/components/schemas/google.example.library.v1.Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' delete: tags: - LibraryService @@ -244,6 +292,12 @@ paths: "200": description: OK content: {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' /v1/shelves/{shelf}/books/{book}:move: post: tags: @@ -278,6 +332,12 @@ paths: application/json: schema: $ref: '#/components/schemas/google.example.library.v1.Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' /v1/shelves/{shelf}:merge: post: tags: @@ -311,6 +371,12 @@ paths: application/json: schema: $ref: '#/components/schemas/google.example.library.v1.Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' components: schemas: google.example.library.v1.Book: @@ -423,5 +489,29 @@ components: description: The last update date and time. format: date-time description: A Shelf contains a collection of books with a theme. + google.protobuf.Any: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + google.rpc.Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/google.protobuf.Any' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: LibraryService diff --git a/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_json.yaml b/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_json.yaml index f5a0697d..e76f4846 100644 --- a/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_json.yaml +++ b/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_json.yaml @@ -45,6 +45,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ListShelvesResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - LibraryService @@ -63,6 +69,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}: get: tags: @@ -83,6 +95,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' delete: tags: - LibraryService @@ -99,6 +117,12 @@ paths: "200": description: OK content: {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}/books: get: tags: @@ -133,6 +157,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ListBooksResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - LibraryService @@ -158,6 +188,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}/books/{book}: get: tags: @@ -184,6 +220,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' put: tags: - LibraryService @@ -222,6 +264,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' delete: tags: - LibraryService @@ -244,6 +292,12 @@ paths: "200": description: OK content: {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}/books/{book}:move: post: tags: @@ -278,6 +332,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}:merge: post: tags: @@ -311,6 +371,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: Book: @@ -346,6 +412,14 @@ components: description: The last update date and time. format: date-time description: A single book in the library. + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. ListBooksResponse: type: object properties: @@ -423,5 +497,21 @@ components: description: The last update date and time. format: date-time description: A Shelf contains a collection of books with a theme. + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: LibraryService diff --git a/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_string_enum.yaml b/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_string_enum.yaml index 3e2736bc..17c57021 100644 --- a/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_string_enum.yaml +++ b/cmd/protoc-gen-openapi/examples/google/example/library/v1/openapi_string_enum.yaml @@ -45,6 +45,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ListShelvesResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - LibraryService @@ -63,6 +69,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}: get: tags: @@ -83,6 +95,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' delete: tags: - LibraryService @@ -99,6 +117,12 @@ paths: "200": description: OK content: {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}/books: get: tags: @@ -133,6 +157,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ListBooksResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - LibraryService @@ -158,6 +188,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}/books/{book}: get: tags: @@ -184,6 +220,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' put: tags: - LibraryService @@ -222,6 +264,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' delete: tags: - LibraryService @@ -244,6 +292,12 @@ paths: "200": description: OK content: {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}/books/{book}:move: post: tags: @@ -278,6 +332,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Book' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/shelves/{shelf}:merge: post: tags: @@ -311,6 +371,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Shelf' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: Book: @@ -346,6 +412,14 @@ components: description: The last update date and time. format: date-time description: A single book in the library. + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. ListBooksResponse: type: object properties: @@ -423,5 +497,21 @@ components: description: The last update date and time. format: date-time description: A Shelf contains a collection of books with a theme. + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: LibraryService diff --git a/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi.yaml b/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi.yaml index 92767908..261792b4 100644 --- a/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi.yaml @@ -30,8 +30,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -39,5 +53,21 @@ components: type: string text: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_default_response.yaml b/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_default_response.yaml new file mode 100644 index 00000000..1643daff --- /dev/null +++ b/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_default_response.yaml @@ -0,0 +1,73 @@ +# Generated with protoc-gen-openapi +# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi + +openapi: 3.0.3 +info: + title: Messaging API + version: 0.0.1 +paths: + /v1/messages/{messageId}: + patch: + tags: + - Messaging + operationId: Messaging_UpdateMessage + parameters: + - name: messageId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: string + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' +components: + schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + Message: + type: object + properties: + messageId: + type: string + text: + type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' +tags: + - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_fq_schema_naming.yaml b/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_fq_schema_naming.yaml index 6d87f9ef..45edf441 100644 --- a/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_fq_schema_naming.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_fq_schema_naming.yaml @@ -30,8 +30,38 @@ paths: application/json: schema: $ref: '#/components/schemas/tests.bodymappying.message.v1.Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' components: schemas: + google.protobuf.Any: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + google.rpc.Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/google.protobuf.Any' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tests.bodymappying.message.v1.Message: type: object properties: diff --git a/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_json.yaml b/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_json.yaml index 49389176..a6caaaee 100644 --- a/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_json.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_json.yaml @@ -30,8 +30,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -39,5 +53,21 @@ components: type: string text: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_string_enum.yaml b/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_string_enum.yaml index 809ef60a..1643daff 100644 --- a/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_string_enum.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/bodymapping/openapi_string_enum.yaml @@ -30,8 +30,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -39,5 +53,21 @@ components: type: string text: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi.yaml b/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi.yaml index c3838f42..11073498 100644 --- a/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi.yaml @@ -34,13 +34,43 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: kind: type: integer format: enum + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_default_response.yaml b/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_default_response.yaml new file mode 100644 index 00000000..11073498 --- /dev/null +++ b/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_default_response.yaml @@ -0,0 +1,76 @@ +# Generated with protoc-gen-openapi +# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi + +openapi: 3.0.3 +info: + title: Messaging API + description: Messaging service + version: 0.0.1 +paths: + /v1/messages/{message_id}: + post: + tags: + - Messaging + operationId: Messaging_CreateMessage + parameters: + - name: message_id + in: path + required: true + schema: + type: string + - name: kind + in: query + schema: + type: integer + format: enum + requestBody: + content: + application/json: {} + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' +components: + schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + Message: + type: object + properties: + kind: + type: integer + format: enum + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' +tags: + - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_fq_schema_naming.yaml b/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_fq_schema_naming.yaml index 4068870a..9f162c6b 100644 --- a/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_fq_schema_naming.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_fq_schema_naming.yaml @@ -34,8 +34,38 @@ paths: application/json: schema: $ref: '#/components/schemas/tests.enumoptions.message.v1.Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' components: schemas: + google.protobuf.Any: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + google.rpc.Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/google.protobuf.Any' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tests.enumoptions.message.v1.Message: type: object properties: diff --git a/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_json.yaml b/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_json.yaml index d1e177a9..9aada7aa 100644 --- a/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_json.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_json.yaml @@ -34,13 +34,43 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: kind: type: integer format: enum + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_string_enum.yaml b/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_string_enum.yaml index 018c8290..641d2eb8 100644 --- a/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_string_enum.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/enumoptions/openapi_string_enum.yaml @@ -38,8 +38,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -50,5 +64,21 @@ components: - KIND_2 type: string format: enum + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi.yaml b/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi.yaml index 383ca904..0e7a8f80 100644 --- a/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi.yaml @@ -35,6 +35,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' patch: tags: - Messaging @@ -62,8 +68,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Message2' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -82,5 +102,21 @@ components: type: string not_used: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_default_response.yaml b/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_default_response.yaml new file mode 100644 index 00000000..d653131a --- /dev/null +++ b/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_default_response.yaml @@ -0,0 +1,123 @@ +# Generated with protoc-gen-openapi +# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi + +openapi: 3.0.3 +info: + title: Messaging API + description: Messaging service + version: 0.0.1 +paths: + /v1/messages/{messageId}: + post: + tags: + - Messaging + operationId: Messaging_CreateMessage + parameters: + - name: messageId + in: path + required: true + schema: + type: string + - name: notUsed + in: query + schema: + type: string + requestBody: + content: + application/json: + schema: + type: string + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v1/messages/{message_id}: + patch: + tags: + - Messaging + operationId: Messaging_UpdateMessage + parameters: + - name: message_id + in: path + required: true + schema: + type: string + - name: not_used + in: query + schema: + type: string + requestBody: + content: + application/json: + schema: + type: string + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Message2' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' +components: + schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + Message: + type: object + properties: + messageId: + type: string + bodyText: + type: string + notUsed: + type: string + Message2: + type: object + properties: + message_id: + type: string + body_text: + type: string + not_used: + type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' +tags: + - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_fq_schema_naming.yaml b/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_fq_schema_naming.yaml index c7a035a6..13ef0fd2 100644 --- a/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_fq_schema_naming.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_fq_schema_naming.yaml @@ -35,6 +35,12 @@ paths: application/json: schema: $ref: '#/components/schemas/tests.jsonnames.message.v1.Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' /v1/messages/{message_id}: patch: tags: @@ -63,8 +69,38 @@ paths: application/json: schema: $ref: '#/components/schemas/tests.jsonnames.message.v1.Message2' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' components: schemas: + google.protobuf.Any: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + google.rpc.Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/google.protobuf.Any' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tests.jsonnames.message.v1.Message: type: object properties: diff --git a/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_json.yaml b/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_json.yaml index f8644e0c..aa75c871 100644 --- a/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_json.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_json.yaml @@ -35,6 +35,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/messages/{message_id}: patch: tags: @@ -63,8 +69,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Message2' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -83,5 +103,21 @@ components: type: string not_used: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_string_enum.yaml b/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_string_enum.yaml index a03c1b1a..d653131a 100644 --- a/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_string_enum.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/jsonoptions/openapi_string_enum.yaml @@ -35,6 +35,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/messages/{message_id}: patch: tags: @@ -63,8 +69,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Message2' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -83,5 +103,21 @@ components: type: string not_used: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi.yaml b/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi.yaml index 7e70d512..82fdf247 100644 --- a/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi.yaml @@ -30,6 +30,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: AnotherMessage: @@ -40,6 +46,14 @@ components: format: int64 label: type: string + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -81,5 +95,21 @@ components: format: int64 label: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_default_response.yaml b/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_default_response.yaml new file mode 100644 index 00000000..7c2a594e --- /dev/null +++ b/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_default_response.yaml @@ -0,0 +1,115 @@ +# Generated with protoc-gen-openapi +# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi + +openapi: 3.0.3 +info: + title: Messaging API + version: 0.0.1 +paths: + /v1/messages/{messageId}: + patch: + tags: + - Messaging + operationId: Messaging_UpdateMessage + parameters: + - name: messageId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' +components: + schemas: + AnotherMessage: + type: object + properties: + id: + type: integer + format: int64 + label: + type: string + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + Message: + type: object + properties: + messageId: + type: string + anotherMessage: + $ref: '#/components/schemas/AnotherMessage' + subMessage: + $ref: '#/components/schemas/Message_SubMessage' + stringList: + type: array + items: + type: string + subMessageList: + type: array + items: + $ref: '#/components/schemas/Message_SubMessage' + objectList: + type: array + items: + type: object + stringsMap: + type: object + additionalProperties: + type: string + subMessagesMap: + type: object + additionalProperties: + $ref: '#/components/schemas/Message_SubMessage' + objectsMap: + type: object + additionalProperties: + type: object + Message_SubMessage: + type: object + properties: + id: + type: integer + format: int64 + label: + type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' +tags: + - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_fq_schema_naming.yaml b/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_fq_schema_naming.yaml index d1823c46..364104b1 100644 --- a/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_fq_schema_naming.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_fq_schema_naming.yaml @@ -30,8 +30,38 @@ paths: application/json: schema: $ref: '#/components/schemas/tests.mapfields.message.v1.Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' components: schemas: + google.protobuf.Any: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + google.rpc.Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/google.protobuf.Any' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tests.mapfields.message.v1.AnotherMessage: type: object properties: diff --git a/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_json.yaml b/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_json.yaml index 5600f548..239a451b 100644 --- a/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_json.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_json.yaml @@ -30,6 +30,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: AnotherMessage: @@ -40,6 +46,14 @@ components: format: int64 label: type: string + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -81,5 +95,21 @@ components: format: int64 label: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_string_enum.yaml b/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_string_enum.yaml index 62ff4b92..7c2a594e 100644 --- a/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_string_enum.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/mapfields/openapi_string_enum.yaml @@ -30,6 +30,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: AnotherMessage: @@ -40,6 +46,14 @@ components: format: int64 label: type: string + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -81,5 +95,21 @@ components: format: int64 label: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi.yaml b/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi.yaml index 16126245..2ea9e80d 100644 --- a/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi.yaml @@ -30,8 +30,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -40,5 +54,21 @@ components: format: int64 label: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging1 diff --git a/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_default_response.yaml b/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_default_response.yaml new file mode 100644 index 00000000..2ea9e80d --- /dev/null +++ b/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_default_response.yaml @@ -0,0 +1,74 @@ +# Generated with protoc-gen-openapi +# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi + +openapi: 3.0.3 +info: + title: Messaging1 API + version: 0.0.1 +paths: + /v1/messages/{message_id}: + patch: + tags: + - Messaging1 + operationId: Messaging1_UpdateMessage + parameters: + - name: message_id + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' +components: + schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + Message: + type: object + properties: + id: + type: integer + format: int64 + label: + type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' +tags: + - name: Messaging1 diff --git a/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_fq_schema_naming.yaml b/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_fq_schema_naming.yaml index d0ce76c3..3806cd38 100644 --- a/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_fq_schema_naming.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_fq_schema_naming.yaml @@ -30,8 +30,38 @@ paths: application/json: schema: $ref: '#/components/schemas/tests.mapfields.message.v1.Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' components: schemas: + google.protobuf.Any: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + google.rpc.Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/google.protobuf.Any' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tests.mapfields.message.v1.Message: type: object properties: diff --git a/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_json.yaml b/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_json.yaml index e6e8fcbe..f95d58e1 100644 --- a/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_json.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_json.yaml @@ -30,8 +30,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -40,5 +54,21 @@ components: format: int64 label: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging1 diff --git a/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_string_enum.yaml b/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_string_enum.yaml index 16126245..2ea9e80d 100644 --- a/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_string_enum.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/noannotations/openapi_string_enum.yaml @@ -30,8 +30,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -40,5 +54,21 @@ components: format: int64 label: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging1 diff --git a/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi.yaml b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi.yaml index 5deebc39..ea423807 100644 --- a/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi.yaml @@ -38,10 +38,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' security: - BasicAuth: [] components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -50,6 +64,22 @@ components: format: int64 label: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' securitySchemes: BasicAuth: type: http diff --git a/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_default_response.yaml b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_default_response.yaml new file mode 100644 index 00000000..ea423807 --- /dev/null +++ b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_default_response.yaml @@ -0,0 +1,88 @@ +# Generated with protoc-gen-openapi +# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi + +openapi: 3.0.3 +info: + title: Title from annotation + description: Description from annotation + contact: + name: Contact Name + url: https://github.com/google/gnostic + email: gnostic@google.com + license: + name: Apache License + url: https://github.com/google/gnostic/blob/master/LICENSE + version: Version from annotation +paths: + /v1/messages/{message_id}: + patch: + tags: + - Messaging1 + operationId: Messaging1_UpdateMessage + parameters: + - name: message_id + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + security: + - BasicAuth: [] +components: + schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + Message: + type: object + properties: + id: + type: integer + format: int64 + label: + type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' + securitySchemes: + BasicAuth: + type: http + scheme: basic +tags: + - name: Messaging1 diff --git a/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_fq_schema_naming.yaml b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_fq_schema_naming.yaml index f3598c5a..d12d0f8e 100644 --- a/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_fq_schema_naming.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_fq_schema_naming.yaml @@ -38,10 +38,40 @@ paths: application/json: schema: $ref: '#/components/schemas/tests.openapiv3annotations.message.v1.Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' security: - BasicAuth: [] components: schemas: + google.protobuf.Any: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + google.rpc.Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/google.protobuf.Any' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tests.openapiv3annotations.message.v1.Message: type: object properties: diff --git a/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_json.yaml b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_json.yaml index 5deebc39..ea423807 100644 --- a/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_json.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_json.yaml @@ -38,10 +38,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' security: - BasicAuth: [] components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -50,6 +64,22 @@ components: format: int64 label: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' securitySchemes: BasicAuth: type: http diff --git a/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_string_enum.yaml b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_string_enum.yaml index 5deebc39..ea423807 100644 --- a/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_string_enum.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_string_enum.yaml @@ -38,10 +38,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' security: - BasicAuth: [] components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -50,6 +64,22 @@ components: format: int64 label: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' securitySchemes: BasicAuth: type: http diff --git a/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi.yaml b/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi.yaml index 21e30e73..ac3eb30d 100644 --- a/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi.yaml @@ -29,6 +29,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - Messaging @@ -52,6 +58,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/users/{user_id}/messages/{message_id}: get: tags: @@ -76,8 +88,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -90,5 +116,21 @@ components: type: string maybe: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_default_response.yaml b/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_default_response.yaml new file mode 100644 index 00000000..e668a88b --- /dev/null +++ b/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_default_response.yaml @@ -0,0 +1,136 @@ +# Generated with protoc-gen-openapi +# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi + +openapi: 3.0.3 +info: + title: Messaging API + version: 0.0.1 +paths: + /v1/messages/{messageId}: + get: + tags: + - Messaging + operationId: Messaging_GetMessage + parameters: + - name: messageId + in: path + required: true + schema: + type: string + - name: userId + in: query + schema: + type: integer + format: uint64 + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - Messaging + operationId: Messaging_CreateMessage + parameters: + - name: messageId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v1/users/{userId}/messages/{messageId}: + get: + tags: + - Messaging + operationId: Messaging_GetUserMessage + parameters: + - name: userId + in: path + required: true + schema: + type: integer + format: uint64 + - name: messageId + in: path + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' +components: + schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + Message: + type: object + properties: + messageId: + type: string + userId: + type: integer + format: uint64 + content: + type: string + maybe: + type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' +tags: + - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_fq_schema_naming.yaml b/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_fq_schema_naming.yaml index 78f57452..0c7fe385 100644 --- a/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_fq_schema_naming.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_fq_schema_naming.yaml @@ -29,6 +29,12 @@ paths: application/json: schema: $ref: '#/components/schemas/tests.pathparams.message.v1.Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' post: tags: - Messaging @@ -52,6 +58,12 @@ paths: application/json: schema: $ref: '#/components/schemas/tests.pathparams.message.v1.Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' /v1/users/{userId}/messages/{messageId}: get: tags: @@ -76,8 +88,38 @@ paths: application/json: schema: $ref: '#/components/schemas/tests.pathparams.message.v1.Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' components: schemas: + google.protobuf.Any: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + google.rpc.Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/google.protobuf.Any' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tests.pathparams.message.v1.Message: type: object properties: diff --git a/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_json.yaml b/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_json.yaml index eb124f04..c1e9a697 100644 --- a/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_json.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_json.yaml @@ -29,6 +29,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - Messaging @@ -52,6 +58,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/users/{userId}/messages/{messageId}: get: tags: @@ -76,8 +88,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -90,5 +116,21 @@ components: type: string maybe: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_string_enum.yaml b/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_string_enum.yaml index 768ab869..e668a88b 100644 --- a/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_string_enum.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/pathparams/openapi_string_enum.yaml @@ -29,6 +29,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - Messaging @@ -52,6 +58,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/users/{userId}/messages/{messageId}: get: tags: @@ -76,8 +88,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Message: type: object properties: @@ -90,5 +116,21 @@ components: type: string maybe: type: string + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tags: - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi.yaml b/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi.yaml index 6f3dc0e6..ef5dc1a9 100644 --- a/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi.yaml @@ -20,6 +20,12 @@ paths: application/json: schema: $ref: '#/components/schemas/GoogleProtobufValue' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/messages/{message_id}: get: tags: @@ -99,6 +105,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - Messaging @@ -122,6 +134,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' patch: tags: - Messaging @@ -206,6 +224,12 @@ paths: application/json: schema: type: object + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/messages:csv: get: tags: @@ -219,6 +243,12 @@ paths: description: OK content: '*/*': {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - Messaging @@ -234,8 +264,22 @@ paths: description: OK content: '*/*': {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. GoogleProtobufValue: description: Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values. Message: @@ -301,6 +345,22 @@ components: format: int32 child: $ref: '#/components/schemas/RecursiveChild' + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' SubMessage: type: object properties: diff --git a/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_default_response.yaml b/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_default_response.yaml new file mode 100644 index 00000000..3099a367 --- /dev/null +++ b/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_default_response.yaml @@ -0,0 +1,382 @@ +# Generated with protoc-gen-openapi +# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi + +openapi: 3.0.3 +info: + title: Messaging API + version: 0.0.1 +servers: + - url: https://foo.googleapi.com +paths: + /v1/messages: + get: + tags: + - Messaging + operationId: Messaging_ListMessages + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GoogleProtobufValue' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v1/messages/{messageId}: + get: + tags: + - Messaging + operationId: Messaging_GetMessage + parameters: + - name: messageId + in: path + required: true + schema: + type: string + - name: stringType + in: query + schema: + type: string + - name: recursiveType.parentId + in: query + schema: + type: integer + format: int32 + - name: recursiveType.child.childId + in: query + schema: + type: integer + format: int32 + - name: recursiveType.child.parent.parentId + in: query + schema: + type: integer + format: int32 + - name: recursiveType.child.parent.child.childId + in: query + schema: + type: integer + format: int32 + - name: embeddedType.messageId + in: query + schema: + type: string + - name: subType.messageId + in: query + schema: + type: string + - name: subType.subSubMessage.messageId + in: query + schema: + type: string + - name: subType.subSubMessage.integers + in: query + schema: + type: array + items: + type: integer + format: int32 + - name: repeatedType + in: query + schema: + type: array + items: + type: string + - name: valueType + in: query + description: Description of value + schema: + $ref: '#/components/schemas/GoogleProtobufValue' + - name: repeatedValueType + in: query + description: Description of repeated value + schema: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufValue' + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - Messaging + operationId: Messaging_CreateMessage + parameters: + - name: messageId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + patch: + tags: + - Messaging + operationId: Messaging_UpdateMessage + parameters: + - name: messageId + in: path + required: true + schema: + type: string + - name: stringType + in: query + schema: + type: string + - name: recursiveType.parentId + in: query + schema: + type: integer + format: int32 + - name: recursiveType.child.childId + in: query + schema: + type: integer + format: int32 + - name: recursiveType.child.parent.parentId + in: query + schema: + type: integer + format: int32 + - name: recursiveType.child.parent.child.childId + in: query + schema: + type: integer + format: int32 + - name: embeddedType.messageId + in: query + schema: + type: string + - name: subType.messageId + in: query + schema: + type: string + - name: subType.subSubMessage.messageId + in: query + schema: + type: string + - name: subType.subSubMessage.integers + in: query + schema: + type: array + items: + type: integer + format: int32 + - name: repeatedType + in: query + schema: + type: array + items: + type: string + - name: valueType + in: query + description: Description of value + schema: + $ref: '#/components/schemas/GoogleProtobufValue' + - name: repeatedValueType + in: query + description: Description of repeated value + schema: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufValue' + requestBody: + content: + application/json: + schema: + type: object + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + type: object + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /v1/messages:csv: + get: + tags: + - Messaging + description: |- + OpenAPI does not allow requestBody in GET operations. + But it should not convert it to query params either. + operationId: Messaging_ListMessagesCSV + responses: + "200": + description: OK + content: + '*/*': {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - Messaging + operationId: Messaging_CreateMessagesFromCSV + requestBody: + content: + application/json: + schema: + type: string + required: true + responses: + "200": + description: OK + content: + '*/*': {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' +components: + schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + GoogleProtobufValue: + description: Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values. + Message: + type: object + properties: + messageId: + type: string + stringType: + type: string + recursiveType: + $ref: '#/components/schemas/RecursiveParent' + embeddedType: + $ref: '#/components/schemas/Message_EmbMessage' + subType: + $ref: '#/components/schemas/SubMessage' + repeatedType: + type: array + items: + type: string + repeatedSubType: + type: array + items: + $ref: '#/components/schemas/SubMessage' + repeatedRecursiveType: + type: array + items: + $ref: '#/components/schemas/RecursiveParent' + mapType: + type: object + additionalProperties: + type: string + body: + type: object + media: + type: array + items: + type: object + valueType: + $ref: '#/components/schemas/GoogleProtobufValue' + repeatedValueType: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufValue' + description: Description of repeated value + Message_EmbMessage: + type: object + properties: + messageId: + type: string + RecursiveChild: + type: object + properties: + childId: + type: integer + format: int32 + parent: + $ref: '#/components/schemas/RecursiveParent' + RecursiveParent: + type: object + properties: + parentId: + type: integer + format: int32 + child: + $ref: '#/components/schemas/RecursiveChild' + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' + SubMessage: + type: object + properties: + messageId: + type: string + subSubMessage: + $ref: '#/components/schemas/SubSubMessage' + SubSubMessage: + type: object + properties: + messageId: + type: string + integers: + type: array + items: + type: integer + format: int32 +tags: + - name: Messaging diff --git a/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_fq_schema_naming.yaml b/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_fq_schema_naming.yaml index 8d109546..cd2c0dd9 100644 --- a/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_fq_schema_naming.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_fq_schema_naming.yaml @@ -20,6 +20,12 @@ paths: application/json: schema: $ref: '#/components/schemas/google.protobuf.Value' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' /v1/messages/{messageId}: get: tags: @@ -99,6 +105,12 @@ paths: application/json: schema: $ref: '#/components/schemas/tests.protobuftypes.message.v1.Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' post: tags: - Messaging @@ -122,6 +134,12 @@ paths: application/json: schema: $ref: '#/components/schemas/tests.protobuftypes.message.v1.Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' patch: tags: - Messaging @@ -206,6 +224,12 @@ paths: application/json: schema: type: object + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' /v1/messages:csv: get: tags: @@ -219,6 +243,12 @@ paths: description: OK content: '*/*': {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' post: tags: - Messaging @@ -234,10 +264,40 @@ paths: description: OK content: '*/*': {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' components: schemas: + google.protobuf.Any: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. google.protobuf.Value: description: Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values. + google.rpc.Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/google.protobuf.Any' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' tests.protobuftypes.message.v1.Message: type: object properties: diff --git a/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_json.yaml b/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_json.yaml index 78ef60a2..cd4064fb 100644 --- a/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_json.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_json.yaml @@ -20,6 +20,12 @@ paths: application/json: schema: $ref: '#/components/schemas/GoogleProtobufValue' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/messages/{messageId}: get: tags: @@ -99,6 +105,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - Messaging @@ -122,6 +134,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' patch: tags: - Messaging @@ -206,6 +224,12 @@ paths: application/json: schema: type: object + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/messages:csv: get: tags: @@ -219,6 +243,12 @@ paths: description: OK content: '*/*': {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - Messaging @@ -234,8 +264,22 @@ paths: description: OK content: '*/*': {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. GoogleProtobufValue: description: Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values. Message: @@ -301,6 +345,22 @@ components: format: int32 child: $ref: '#/components/schemas/RecursiveChild' + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' SubMessage: type: object properties: diff --git a/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_string_enum.yaml b/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_string_enum.yaml index 12d00f13..3099a367 100644 --- a/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_string_enum.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/protobuftypes/openapi_string_enum.yaml @@ -20,6 +20,12 @@ paths: application/json: schema: $ref: '#/components/schemas/GoogleProtobufValue' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/messages/{messageId}: get: tags: @@ -99,6 +105,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - Messaging @@ -122,6 +134,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Message' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' patch: tags: - Messaging @@ -206,6 +224,12 @@ paths: application/json: schema: type: object + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /v1/messages:csv: get: tags: @@ -219,6 +243,12 @@ paths: description: OK content: '*/*': {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' post: tags: - Messaging @@ -234,8 +264,22 @@ paths: description: OK content: '*/*': {} + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. GoogleProtobufValue: description: Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values. Message: @@ -301,6 +345,22 @@ components: format: int32 child: $ref: '#/components/schemas/RecursiveChild' + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' SubMessage: type: object properties: diff --git a/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi.yaml b/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi.yaml index d2531bb7..077d2b5a 100644 --- a/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi.yaml @@ -18,6 +18,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: GoogleProtobufAny: @@ -25,6 +31,7 @@ components: properties: '@type': type: string + description: The type of the serialized message. additionalProperties: true description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Status: diff --git a/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_default_response.yaml b/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_default_response.yaml new file mode 100644 index 00000000..077d2b5a --- /dev/null +++ b/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_default_response.yaml @@ -0,0 +1,54 @@ +# Generated with protoc-gen-openapi +# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi + +openapi: 3.0.3 +info: + title: Status API + version: 0.0.1 +paths: + /v1/status: + get: + tags: + - Status + operationId: Status_GetStatus + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' +components: + schemas: + GoogleProtobufAny: + type: object + properties: + '@type': + type: string + description: The type of the serialized message. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + Status: + type: object + properties: + code: + type: integer + description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. + format: int32 + message: + type: string + description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. + details: + type: array + items: + $ref: '#/components/schemas/GoogleProtobufAny' + description: A list of messages that carry the error details. There is a common set of message types for APIs to use. + description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).' +tags: + - name: Status diff --git a/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_fq_schema_naming.yaml b/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_fq_schema_naming.yaml index 5f63dbc9..15abe7da 100644 --- a/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_fq_schema_naming.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_fq_schema_naming.yaml @@ -18,6 +18,12 @@ paths: application/json: schema: $ref: '#/components/schemas/google.rpc.Status' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/google.rpc.Status' components: schemas: google.protobuf.Any: @@ -25,6 +31,7 @@ components: properties: '@type': type: string + description: The type of the serialized message. additionalProperties: true description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. google.rpc.Status: diff --git a/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_json.yaml b/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_json.yaml index ed9a6b52..ef2df5f4 100644 --- a/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_json.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_json.yaml @@ -18,6 +18,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: GoogleProtobufAny: @@ -25,6 +31,7 @@ components: properties: '@type': type: string + description: The type of the serialized message. additionalProperties: true description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Status: diff --git a/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_string_enum.yaml b/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_string_enum.yaml index d2531bb7..077d2b5a 100644 --- a/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_string_enum.yaml +++ b/cmd/protoc-gen-openapi/examples/tests/rpctypes/openapi_string_enum.yaml @@ -18,6 +18,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' components: schemas: GoogleProtobufAny: @@ -25,6 +31,7 @@ components: properties: '@type': type: string + description: The type of the serialized message. additionalProperties: true description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. Status: diff --git a/cmd/protoc-gen-openapi/generator/generator.go b/cmd/protoc-gen-openapi/generator/generator.go index 48f405a4..74a0af74 100644 --- a/cmd/protoc-gen-openapi/generator/generator.go +++ b/cmd/protoc-gen-openapi/generator/generator.go @@ -24,28 +24,37 @@ import ( "strings" "google.golang.org/genproto/googleapis/api/annotations" + status_pb "google.golang.org/genproto/googleapis/rpc/status" "google.golang.org/protobuf/compiler/protogen" "google.golang.org/protobuf/proto" "google.golang.org/protobuf/reflect/protoreflect" + any_pb "google.golang.org/protobuf/types/known/anypb" wk "github.com/google/gnostic/cmd/protoc-gen-openapi/generator/wellknown" v3 "github.com/google/gnostic/openapiv3" ) type Configuration struct { - Version *string - Title *string - Description *string - Naming *string - EnumType *string - CircularDepth *int - FQSchemaNaming *bool + Version *string + Title *string + Description *string + Naming *string + FQSchemaNaming *bool + EnumType *string + CircularDepth *int + DefaultResponse *bool } const ( infoURL = "https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi" ) +// In order to dynamically add google.rpc.Status responses we need +// to know the message descriptors for google.rpc.Status as well +// as google.protobuf.Any. +var statusProtoDesc = (&status_pb.Status{}).ProtoReflect().Descriptor() +var anyProtoDesc = (&any_pb.Any{}).ProtoReflect().Descriptor() + // OpenAPIv3Generator holds internal state needed to generate an OpenAPIv3 document for a transcoded Protocol Buffer service. type OpenAPIv3Generator struct { conf Configuration @@ -122,7 +131,7 @@ func (g *OpenAPIv3Generator) buildDocumentV3() *v3.Document { for len(g.reflect.requiredSchemas) > 0 { count := len(g.reflect.requiredSchemas) for _, file := range g.plugin.Files { - g.addSchemasToDocumentV3(d, file.Messages) + g.addSchemasForMessagesToDocumentV3(d, file.Messages) } g.reflect.requiredSchemas = g.reflect.requiredSchemas[count:len(g.reflect.requiredSchemas)] } @@ -370,6 +379,7 @@ func (g *OpenAPIv3Generator) _buildQueryParamsV3(field *protogen.Field, depths m // buildOperationV3 constructs an operation for a set of values. func (g *OpenAPIv3Generator) buildOperationV3( + d *v3.Document, operationID string, tagName string, description string, @@ -504,6 +514,33 @@ func (g *OpenAPIv3Generator) buildOperationV3( }, } + // Add the default reponse if needed + if *g.conf.DefaultResponse { + anySchemaName := g.reflect.formatMessageName(anyProtoDesc) + anySchema := wk.NewGoogleProtobufAnySchema(anySchemaName) + g.addSchemaToDocumentV3(d, anySchema) + + statusSchemaName := g.reflect.formatMessageName(statusProtoDesc) + statusSchema := wk.NewGoogleRpcStatusSchema(statusSchemaName, anySchemaName) + g.addSchemaToDocumentV3(d, statusSchema) + + defaultResponse := &v3.NamedResponseOrReference{ + Name: "default", + Value: &v3.ResponseOrReference{ + Oneof: &v3.ResponseOrReference_Response{ + Response: &v3.Response{ + Description: "Default error response", + Content: wk.NewApplicationJsonMediaType(&v3.SchemaOrReference{ + Oneof: &v3.SchemaOrReference_Reference{ + Reference: &v3.Reference{XRef: "#/components/schemas/" + statusSchemaName}}}), + }, + }, + }, + } + + responses.ResponseOrReference = append(responses.ResponseOrReference, defaultResponse) + } + // Create the operation. op := &v3.Operation{ Tags: []string{tagName}, @@ -652,7 +689,7 @@ func (g *OpenAPIv3Generator) addPathsToDocumentV3(d *v3.Document, services []*pr defaultHost := proto.GetExtension(service.Desc.Options(), annotations.E_DefaultHost).(string) op, path2 := g.buildOperationV3( - operationID, service.GoName, comment, defaultHost, path, body, inputMessage, outputMessage) + d, operationID, service.GoName, comment, defaultHost, path, body, inputMessage, outputMessage) // Merge any `Operation` annotations with the current extOperation := proto.GetExtension(method.Desc.Options(), v3.E_Operation) @@ -671,36 +708,46 @@ func (g *OpenAPIv3Generator) addPathsToDocumentV3(d *v3.Document, services []*pr } } -// addSchemasToDocumentV3 adds info from one file descriptor. -func (g *OpenAPIv3Generator) addSchemasToDocumentV3(d *v3.Document, messages []*protogen.Message) { +// addSchemaForMessageToDocumentV3 adds the schema to the document if required +func (g *OpenAPIv3Generator) addSchemaToDocumentV3(d *v3.Document, schema *v3.NamedSchemaOrReference) { + if contains(g.generatedSchemas, schema.Name) { + return + } + g.generatedSchemas = append(g.generatedSchemas, schema.Name) + d.Components.Schemas.AdditionalProperties = append(d.Components.Schemas.AdditionalProperties, schema) +} + +// addSchemasForMessagesToDocumentV3 adds info from one file descriptor. +func (g *OpenAPIv3Generator) addSchemasForMessagesToDocumentV3(d *v3.Document, messages []*protogen.Message) { // For each message, generate a definition. for _, message := range messages { if message.Messages != nil { - g.addSchemasToDocumentV3(d, message.Messages) + g.addSchemasForMessagesToDocumentV3(d, message.Messages) } - typeName := g.reflect.fullMessageTypeName(message.Desc) + schemaName := g.reflect.formatMessageName(message.Desc) // Only generate this if we need it and haven't already generated it. - if !contains(g.reflect.requiredSchemas, typeName) || - contains(g.generatedSchemas, typeName) { + if !contains(g.reflect.requiredSchemas, schemaName) || + contains(g.generatedSchemas, schemaName) { continue } - g.generatedSchemas = append(g.generatedSchemas, typeName) + typeName := g.reflect.fullMessageTypeName(message.Desc) messageDescription := g.filterCommentString(message.Comments.Leading, true) // `google.protobuf.Value` and `google.protobuf.Any` have special JSON transcoding // so we can't just reflect on the message descriptor. if typeName == ".google.protobuf.Value" { - d.Components.Schemas.AdditionalProperties = append(d.Components.Schemas.AdditionalProperties, - wk.NewGoogleProtobufValueSchema(g.reflect.formatMessageName(message.Desc)), - ) + g.addSchemaToDocumentV3(d, wk.NewGoogleProtobufValueSchema(schemaName)) continue } else if typeName == ".google.protobuf.Any" { - d.Components.Schemas.AdditionalProperties = append(d.Components.Schemas.AdditionalProperties, - wk.NewGoogleProtobufAnySchema(g.reflect.formatMessageName(message.Desc)), - ) + g.addSchemaToDocumentV3(d, wk.NewGoogleProtobufAnySchema(schemaName)) + continue + } else if typeName == ".google.rpc.Status" { + anySchemaName := g.reflect.formatMessageName(anyProtoDesc) + g.addSchemaToDocumentV3(d, wk.NewGoogleProtobufAnySchema(anySchemaName)) + g.addSchemaToDocumentV3(d, wk.NewGoogleRpcStatusSchema(schemaName, anySchemaName)) continue } @@ -758,21 +805,20 @@ func (g *OpenAPIv3Generator) addSchemasToDocumentV3(d *v3.Document, messages []* }, ) } + // Add the schema to the components.schema list. - d.Components.Schemas.AdditionalProperties = append(d.Components.Schemas.AdditionalProperties, - &v3.NamedSchemaOrReference{ - Name: g.reflect.formatMessageName(message.Desc), - Value: &v3.SchemaOrReference{ - Oneof: &v3.SchemaOrReference_Schema{ - Schema: &v3.Schema{ - Type: "object", - Description: messageDescription, - Properties: definitionProperties, - Required: required, - }, + g.addSchemaToDocumentV3(d, &v3.NamedSchemaOrReference{ + Name: schemaName, + Value: &v3.SchemaOrReference{ + Oneof: &v3.SchemaOrReference_Schema{ + Schema: &v3.Schema{ + Type: "object", + Description: messageDescription, + Properties: definitionProperties, + Required: required, }, }, }, - ) + }) } } diff --git a/cmd/protoc-gen-openapi/generator/reflector.go b/cmd/protoc-gen-openapi/generator/reflector.go index 02a476aa..4dfa861b 100644 --- a/cmd/protoc-gen-openapi/generator/reflector.go +++ b/cmd/protoc-gen-openapi/generator/reflector.go @@ -115,13 +115,15 @@ func (r *OpenAPIv3Reflector) responseContentForMessage(message protoreflect.Mess } func (r *OpenAPIv3Reflector) schemaReferenceForMessage(message protoreflect.MessageDescriptor) string { - typeName := r.fullMessageTypeName(message) - if !contains(r.requiredSchemas, typeName) { - r.requiredSchemas = append(r.requiredSchemas, typeName) + schemaName := r.formatMessageName(message) + if !contains(r.requiredSchemas, schemaName) { + r.requiredSchemas = append(r.requiredSchemas, schemaName) } - return "#/components/schemas/" + r.formatMessageName(message) + return "#/components/schemas/" + schemaName } +// Returns a full schema for simple types, and a schema reference for complex types that reference +// the definition in `#/components/schemas/` func (r *OpenAPIv3Reflector) schemaOrReferenceForMessage(message protoreflect.MessageDescriptor) *v3.SchemaOrReference { typeName := r.fullMessageTypeName(message) switch typeName { diff --git a/cmd/protoc-gen-openapi/generator/wellknown/schemas.go b/cmd/protoc-gen-openapi/generator/wellknown/schemas.go index 96a3bbd9..296d3f4f 100644 --- a/cmd/protoc-gen-openapi/generator/wellknown/schemas.go +++ b/cmd/protoc-gen-openapi/generator/wellknown/schemas.go @@ -158,7 +158,8 @@ func NewGoogleProtobufAnySchema(name string) *v3.NamedSchemaOrReference { Value: &v3.SchemaOrReference{ Oneof: &v3.SchemaOrReference_Schema{ Schema: &v3.Schema{ - Type: "string", + Type: "string", + Description: "The type of the serialized message.", }, }, }, @@ -176,6 +177,70 @@ func NewGoogleProtobufAnySchema(name string) *v3.NamedSchemaOrReference { } } +// google.rpc.Status is handled specially +func NewGoogleRpcStatusSchema(name string, any_name string) *v3.NamedSchemaOrReference { + return &v3.NamedSchemaOrReference{ + Name: name, + Value: &v3.SchemaOrReference{ + Oneof: &v3.SchemaOrReference_Schema{ + Schema: &v3.Schema{ + Type: "object", + Description: "The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).", + Properties: &v3.Properties{ + AdditionalProperties: []*v3.NamedSchemaOrReference{ + { + Name: "code", + Value: &v3.SchemaOrReference{ + Oneof: &v3.SchemaOrReference_Schema{ + Schema: &v3.Schema{ + Type: "integer", + Format: "int32", + Description: "The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].", + }, + }, + }, + }, + { + Name: "message", + Value: &v3.SchemaOrReference{ + Oneof: &v3.SchemaOrReference_Schema{ + Schema: &v3.Schema{ + Type: "string", + Description: "A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.", + }, + }, + }, + }, + { + Name: "details", + Value: &v3.SchemaOrReference{ + Oneof: &v3.SchemaOrReference_Schema{ + Schema: &v3.Schema{ + Type: "array", + Items: &v3.ItemsItem{ + SchemaOrReference: []*v3.SchemaOrReference{ + { + Oneof: &v3.SchemaOrReference_Reference{ + Reference: &v3.Reference{ + XRef: "#/components/schemas/" + any_name, + }, + }, + }, + }, + }, + Description: "A list of messages that carry the error details. There is a common set of message types for APIs to use.", + }, + }, + }, + }, + }, + }, + }, + }, + }, + } +} + func NewGoogleProtobufMapFieldEntrySchema(value_field_schema *v3.SchemaOrReference) *v3.SchemaOrReference { return &v3.SchemaOrReference{ Oneof: &v3.SchemaOrReference_Schema{ diff --git a/cmd/protoc-gen-openapi/main.go b/cmd/protoc-gen-openapi/main.go index aa509760..d8378981 100644 --- a/cmd/protoc-gen-openapi/main.go +++ b/cmd/protoc-gen-openapi/main.go @@ -27,13 +27,14 @@ var flags flag.FlagSet func main() { conf := generator.Configuration{ - Version: flags.String("version", "0.0.1", "version number text, e.g. 1.2.3"), - Title: flags.String("title", "", "name of the API"), - Description: flags.String("description", "", "description of the API"), - Naming: flags.String("naming", "json", `naming convention. Use "proto" for passing names directly from the proto files`), - FQSchemaNaming: flags.Bool("fq_schema_naming", false, `schema naming convention. If "true", generates fully-qualified schema names by prefixing them with the proto message package name`), - EnumType: flags.String("enum_type", "integer", `type for enum serialization. Use "string" for string-based serialization`), - CircularDepth: flags.Int("depth", 2, "depth of recursion for circular messages"), + Version: flags.String("version", "0.0.1", "version number text, e.g. 1.2.3"), + Title: flags.String("title", "", "name of the API"), + Description: flags.String("description", "", "description of the API"), + Naming: flags.String("naming", "json", `naming convention. Use "proto" for passing names directly from the proto files`), + FQSchemaNaming: flags.Bool("fq_schema_naming", false, `schema naming convention. If "true", generates fully-qualified schema names by prefixing them with the proto message package name`), + EnumType: flags.String("enum_type", "integer", `type for enum serialization. Use "string" for string-based serialization`), + CircularDepth: flags.Int("depth", 2, "depth of recursion for circular messages"), + DefaultResponse: flags.Bool("default_response", true, `add default response. If "true", automatically adds a default response to operations which use the google.rpc.Status message. Useful if you use envoy or grpc-gateway to transcode as they use this type for their default error responses.`), } opts := protogen.Options{ diff --git a/cmd/protoc-gen-openapi/plugin_test.go b/cmd/protoc-gen-openapi/plugin_test.go index 58b5a615..49645dc4 100644 --- a/cmd/protoc-gen-openapi/plugin_test.go +++ b/cmd/protoc-gen-openapi/plugin_test.go @@ -221,3 +221,40 @@ func TestOpenAPIStringEnums(t *testing.T) { }) } } + +func TestOpenAPIDefaultResponse(t *testing.T) { + for _, tt := range openapiTests { + fixture := path.Join(tt.path, "openapi_default_response.yaml") + if _, err := os.Stat(fixture); errors.Is(err, os.ErrNotExist) { + if !GENERATE_FIXTURES { + continue + } + } + t.Run(tt.name, func(t *testing.T) { + // Run protoc and the protoc-gen-openapi plugin to generate an OpenAPI spec with string Enums. + err := exec.Command("protoc", + "-I", "../../", + "-I", "../../third_party", + "-I", "examples", + path.Join(tt.path, tt.protofile), + "--openapi_out=default_response=true:.").Run() + if err != nil { + t.Fatalf("protoc failed: %+v", err) + } + if GENERATE_FIXTURES { + err := CopyFixture(TEMP_FILE, fixture) + if err != nil { + t.Fatalf("Can't generate fixture: %+v", err) + } + } else { + // Verify that the generated spec matches our expected version. + err = exec.Command("diff", TEMP_FILE, fixture).Run() + if err != nil { + t.Fatalf("diff failed: %+v", err) + } + } + // if the test succeeded, clean up + os.Remove(TEMP_FILE) + }) + } +}