Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
aazizpc opened this issue Jan 29, 2024 · 1 comment
Open

Comments

@aazizpc
Copy link

aazizpc commented Jan 29, 2024

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
  1. 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
@2minchul
Copy link

It seems like this has been an issue for a while, but I still haven't found a solution.
I think this problem is related to the following:

If anyone knows a solution, please help.

oxisto added a commit to oxisto/gnostic that referenced this issue Aug 18, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants