grpc-ecosystem/grpc-gateway

Example and pattern annotations are not respect for query and path parameters

Open

#4130 opened on Mar 22, 2024

View on GitHub
 (8 comments) (0 reactions) (0 assignees)Go (16,971 stars) (2,250 forks)batch import
bughelp wantedopenapi

Description

🐛 Bug Report

Using the sample proto below, only default appears in the output json - example and pattern do not.

To Reproduce

message GetTileForImageRequest {
	// The unique reference number of the image.
	string image_urn = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
		example: "urn:eagleview.com:v4:spatial-data:raster:visual:ated:QIgDbfZw-kqKfTxbMQXwhw:0",
		default: "urn:eagleview.com:v4:spatial-data:raster:visual:ated:QIgDbfZw-kqKfTxbMQXwhw:0",
		pattern: "^(urn:eagleview\\.com:v\\d+:spatial-data:\\w+:\\w+:\\w+:[A-Za-z0-9-_]+):(\\d+)$",
	}];
}

I'm using buf to generate the swagger using the following template:

buf.gen.swagger.yaml:

version: v1
plugins:
  - name: openapiv2
    out: build/go
    opt:
      - json_names_for_fields=false
      - visibility_restriction_selectors=LATEST

$ buf generate --template buf.gen.swagger.yaml --path proto/evt/iw/service

Expected behaviour

{
  "name": "image_urn",
  "description": "The unique reference number of the image.",
  "in": "path",
  "required": true,
  "type": "string",
  "example": "urn:eagleview.com:v4:spatial-data:raster:visual:ated:QIgDbfZw-kqKfTxbMQXwhw:0",
  "default": "urn:eagleview.com:v4:spatial-data:raster:visual:ated:QIgDbfZw-kqKfTxbMQXwhw:0",
  "pattern": "^(urn:eagleview\\.com:v\\d+:spatial-data:\\w+:\\w+:\\w+:[A-Za-z0-9-_]+):(\\d+)$"
}

Actual Behavior

{
  "name": "image_urn",
  "description": "The unique reference number of the image.",
  "in": "path",
  "required": true,
  "type": "string",
  "default": "urn:eagleview.com:v4:spatial-data:raster:visual:ated:QIgDbfZw-kqKfTxbMQXwhw:0"
}

Your Environment

$ uname -a
Linux 0664eeb787b5 5.14.0-1049-oem #56-Ubuntu SMP Fri Aug 12 10:23:08 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux

$ protoc --version
libprotoc 25.3
Package Version
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway v2.19.1
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2 v2.19.1
google.golang.org/protobuf/cmd/protoc-gen-go v1.32.0

Contributor guide

Tech stack
gorest api
Domain
apibackend
Issue type
bug
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.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Go programming basicsProtocol BuffersgRPC conceptOpenAPI/Swagger
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60
Research direction
Investigate the grpc gateway v2 protoc gen openapiv2 plugin's field option handling, specifically around query and path parameters. Look at how 'example' and 'pattern' annotations are processed compared to 'default'. The issue suggests that only 'default' is included in the output; examine the code in the 'protoc gen openapiv2' package, possibly in files related to field annotation parsing. Cross reference with any existing tests for similar annotations.