Adding Error message to OpenAPI component schema

[linuxluigi]

Is it possible to add a protobuff message to an OpenAPI schema component output?

I want to have a way to add a reference for an error case like 403.

Example:

service ExampleAPI {
    rpc GetCurrentUser(google.protobuf.Empty) returns (UserResponse) {
        option (google.api.http) = {
            get: "/v1/current-user"
        };
        option (gnostic.openapi.v3.operation) = {
            description: "";
            responses: {
                response_or_reference: {
                    name: "403"
                    value: {
                        response: {
                            description: "Forbidden"
                            content: {
                                additional_properties: [{
                                    name: "*/*";
                                    value: {
                                        schema: {
                                               reference: { _ref: "#/components/schemas/ErrorResponse"; }
                                            }
                                        }
                                    }
                                }]
                            }
                        }
                    }
                }
            }
        };
    }
}

message UserResponse {
    int id = 1;
    string name = 2;
}

message ErrorResponse {
    string message = 1;
}

Is this possible right now, or what would be the way to go for adding Error messages to OpenAPI Spec component?

[AaronJan]

I'm also wondering how to do this (switched from grpc-gateway).

In grpc-gateway, you can reference messages in the same proto file, in gnostic, I only found one way, that is manually write those common schemas in the top option (openapi.v3.document) { ... } section.

The problem is you can't annotate a proto message as a component.

[jeffsawatzky]

That should be possible as there are example tests that do something similar.

https://github.com/google/gnostic/blob/ade94e0d08cb9c60272a311608cd5dabd30d1813/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/message.proto

You might need to change the package name from gnostic.openapi.v3 to openapi.v3 though.

Do you have the default_response option enabled? Perhaps it's wiping out your custom one?

[kotyara85]

@jeffsawatzky is this possible to set that for every single rpc without copy-pasting?

[jeffsawatzky]

You can define some global schemas at the file level using the openapi.v3.document option as seen here.

Then you can reference them later on in your rpcs at the rpc level using the openapi.v3.operation options as seen here.

Any settings you specify in the openapi.v3.operation option will merge/override any automatically derived settings.

I don't know if that answers your question though.

There is the default_response as described in the README, but that will use the google.rpc.Status message as the default response (which is the default return message for grpc-gateway, envoy, and other similar HTTP/JSON<->gRPC transcoders).