Proto to OpenAPIv3 - How to annotate Query Parameters as "required"? #427
Description
Hi, I have a gRPC implementation of REST services. It's divided across two proto files - one for the operations and one for the request and response messages.
One of them, a GET Service, accepts a single query parameter as input, which I want to annotate as "required" so that I can use the openApiv3 converter and get that information into the OpenAPI yaml spec.
I tried to do it in the following two ways:
- Adding it to the message, and not the operation, just like how we do with the JSON payload values.
Proto Annotation:
message GetEngagementsRequest {
option (openapi.v3.schema) = {
title: "Engagements Request";
required: "crn";
};
string crn = 1 [
(openapi.v3.property) = {
example: {
yaml: "crn123",
}
title: "Customer reference number";
min_length: 1;
}
];
}
There's no mention of "required" in the yaml file output:
OpenAPI YAML file:
/engagements/get-engagements/v1:
get:
tags:
- Entitlement
operationId: Entitlement_GetEngagements
parameters:
- name: crn
in: query
schema:
type: string
- Tried to set the parameter as required in the operation level using the annotations below.
Proto Annotation:
rpc GetEngagements(model.GetEngagementRequest) returns (model.GetEngagementResponse) {
option (google.api.http) = {
get: "/engagement/get-engagements/v1"
};
option (openapi.v3.operation) = {
description: "Get engagements";
parameters: [
{
parameter:
{
name: "crn";
required: true;
in: "query";
example: {
yaml: "crn123",
}
description: "Customer reference number";
schema: {
schema:
{
type: "string"
}
}
}
}
]
};
}
This seems to work, but brings a duplicate one from the request message.
OpenAPI YAML:
/engagements/get-engagements/v1:
get:
tags:
- Entitlement
description: Get Engagements
operationId: Entitlement_GetEngagements
parameters:
- name: crn
in: query
schema:
type: string
- name: crn
in: query
description: Customer reference number
required: true
schema:
type: string
example: crn123