grpc-ecosystem/grpc-gateway

Options defined in the OpenAPI config file should take precedence over configs in the Proto file

Open

#2891 opened on Sep 16, 2022

View on GitHub
 (2 comments) (1 reaction) (0 assignees)Go (16,971 stars) (2,250 forks)batch import
buggood first issuehelp wantedopenapi

Description

🚀 Feature

As pointed out in #2858, users usually use the openapi configuration file when they can't edit the protobuf file for some reason. So it would be better for the options defined in the openapi configuration file to take precedence.

Currently, only Service has been modified to give priority to the options defined in the OpenAPI configuration file, while the Method, Message, File and Field still give priority to the options defined in the Proto file.

What we need to do

Fix each getXxxOpenAPIOption method so that it first retrieves the options defined in the OpenAPI configuration file, and uses the values defined in the Proto file only if the OpenAPI config options are empty.

It would be nice to check if the automatically generated examples do not change and add some test cases if needed.

For Method, we may need to fix the function below. https://github.com/grpc-ecosystem/grpc-gateway/blob/031bc11c5e7a7ed791f0325cbc01f715ae6714bf/protoc-gen-openapiv2/internal/genopenapi/template.go#L2488

Service has already been fixed. You can refer to the following implementation when fixing the others. https://github.com/grpc-ecosystem/grpc-gateway/blob/031bc11c5e7a7ed791f0325cbc01f715ae6714bf/protoc-gen-openapiv2/internal/genopenapi/template.go#L2518

I think we need to add notes to the doc, as changing the configuration files' priority may impact existing users.

Contributor guide

Tech stack
gogrpc
Domain
apibackend
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Go programminggRPC basicsOpenAPI config
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
55
Research direction
Start by examining the existing implementation for Service (template.go line 2518) and then apply similar logic to Method (line 2488), Message, File, and Field getXxxOpenAPIOption methods. Ensure that options from the OpenAPI config file take precedence over Proto defined options. After modifying, run the existing tests to verify no unintended changes in generated examples, and add new test cases for the updated priority behavior.