google / google/gnostic

Proto to OpenAPIv3 - How to annotate Query Parameters as "required"?

Open
#427 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
2.3k
Forks
279
PR merge metrics
No merged PRs in 30d

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:
1. 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
```

2. 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
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.