gnostic
gnostic copied to clipboard
Adding Error message to OpenAPI component schema
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?
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.
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?
@jeffsawatzky is this possible to set that for every single rpc without copy-pasting?
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).