OpenAPI Generation Issue: Empty Specification for Protocol Buffer Service

[yankarinRG]

Issue Summary:
I am experiencing a problem with the Gnostic library and the protoc-gen-openapi plugin when generating an OpenAPI specification from a Protocol Buffer service. The generated OpenAPI specification is empty and does not reflect the contents of the Protocol Buffer service definition.

Steps to Reproduce:

1. Create a Protocol Buffer service definition, like the one in Attachment 1.
2. Use the following command to generate the OpenAPI specification:
   protoc petstore.proto -I=. --openapi_out=.
3. Examine the generated OpenAPI YAML specification (Attachment 2), which is expected to describe the Protocol Buffer service.

Expected Behavior:
The generated OpenAPI specification should accurately represent the Protocol Buffer service and its endpoints, including any request and response message types.

Actual Behavior:
The generated OpenAPI specification is empty, with no paths, components, or schemas, and it does not reflect the structure of the Protocol Buffer service.

Attachments:

1. Input Protobuf service (petstore.proto)

syntax = "proto3";

package swaggerpetstore_openapi3_1;

option go_package = "swaggerpetstore/openapi3_1";

message GetPetByIdRequest {
    // ID of pet to return
    int64 petId = 1;
}

message Pet {
  int64 id = 1;
  string name = 2;
  Category category = 3;
  repeated string photoUrls = 4;
  repeated Tag tags = 5;
  string status = 6;

  message Category {
    int64 id = 1;
    string name = 2;
  }

  message Tag {
    int64 id = 1;
    string name = 2;
  }
}

service SwaggerPetstoreOpenAPI31Service {
    // Find pet by ID
    //
    // Returns a single pet
    rpc GetPetById(GetPetByIdRequest) returns (Pet) {}
}

2. Output OpenAPI definition (openapi.yaml)

# Generated with protoc-gen-openapi
# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi

openapi: 3.0.3
info:
    title: ""
    version: 0.0.1
paths: {}
components:
    schemas: {}

Additional Information:
Go Version: go1.21.4 windows/amd64
Gnostic Library Version: installed with go install github.com/google/gnostic@latest so I guess v0.7.0 (?)
Protocol Buffer Compiler Version: libprotoc 25.0 (protoc-25.0-win64)
Operating System: Windows 11 Enterprise build 22631

[zaakn]

You may read these guidance to know how to define http service (by proto option, etc.) for grpc service:
https://google.aip.dev/127
https://github.com/googleapis/googleapis/blob/master/google/api/http.proto

[yankarinRG]

You may read these guidance to know how to define http service (by proto option, etc.) for grpc service: https://google.aip.dev/127 https://github.com/googleapis/googleapis/blob/master/google/api/http.proto

Hi there! I followed the steps outlined in point 2 of the Steps to Reproduce section, using the Protocol Buffer service definition provided in the second link you posted. Unfortunately, the result remains consistent with what was described in point 2 of the Attachments section—an empty OpenAPI definition.

This outcome leads me to believe that the issue may not be rooted in the Protocol Buffer service definition itself. I'd like to emphasize that I'm not attempting to execute this command against a sample petstore service but rather against a service from Google, specifically the Maps Booking API. Therefore, it seems the problem might be originating elsewhere in the process.

If you have any insights or suggestions on how to troubleshoot this further, I'd greatly appreciate your guidance.

[zaakn]

1. Make a copy for google/api directory into your "include" path (e.g. /usr/local/include/ on Linux) to ready for being imported.
   Copy from google/api and keep google directory structure. See also the Using these protos paragraph in README.md, which points out several usual files.
2. Define http option.
3. Do it, protoc -I . -I ./include --openapi_out . ./petstore.proto.

files structrure:

.
├── include
│   └── google
│       └── api
│           ├── annotations.proto
│           └── http.proto
└── petstore.proto

petstore.proto:

syntax = "proto3";

package swaggerpetstore_openapi3_1;

option go_package = "swaggerpetstore/openapi3_1";

import "google/api/annotations.proto";

message GetPetByIdRequest {
	int64 pet_id = 1;
}

message Pet {
	int64 id = 1;
	string name = 2;
	Category category = 3;
	repeated string photo_urls = 4;
	repeated Tag tags = 5;
	string status = 6;

	message Category {
		int64 id = 1;
		string name = 2;
	}
	message Tag {
		int64 id = 1;
		string name = 2;
	}
}

service SwaggerPetstoreOpenAPI31Service {
	rpc GetPetById(GetPetByIdRequest) returns(Pet) {
		option(google.api.http) = {
			get: "/pets"
		};
	}
}

[yankarinRG]

Thank you for your guidance! I successfully followed the steps you provided and was able to generate the OpenAPI description for your version of the petstore.proto service (mine is still empty).

Here's the command I used:

protoc -I . -I "%userprofile%\Downloads\protoc-25.0-win64\include" --openapi_out . petstore2.proto

Encouraged by this success, I attempted to replicate the process with the actual Protocol Buffer service I need to convert to OpenAPI. However, I encountered an issue as the command failed to produce the expected result. I find this puzzling since the Protocol Buffer definition is sourced from Google and is unlikely to be malformed.

Any insights or suggestions on why this might be happening would be greatly appreciated.

[yankarinRG]

Upon annotating the various rpcs of the service with HTTP methods and endpoint names, I observed that the OpenAPI definition was generated correctly. Is there any documentation or specification indicating that this annotation step is a prerequisite for correct OpenAPI generation?

[shivbatra]

If we don't define option annotation with google.api.http in the rpc defined . Can we generate openApi spec yaml file.

I am running by doing this getting Empty Specifications.