Automatically annotate using x-go-type

[NPellet]

🚀 Feature

In a way I'm a bit surprised this hasn't been done / hasn't been requested.

Given the content of the proto file, it would be quite easy to generate the x-go-type annotation automatically for the OpenAPIv2 spec file, such that go-swagger can re-use the go type and not regenerate a new one. We use a monorepo, so for us this is super powerful.

I've managed to get it going using

option go_package = "<path/to/my/package>";

message <TypeName> {
   option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
        json_schema: {
          extensions: {
            key: "x-go-type"
            value: {
                struct_value: { 
                    fields: {
                        key: "type",
                        value: { string_value: "<TypeName>" }
                    },
                    fields: {
                        key: "import",
                        value: { 
                            struct_value: {
                                fields: {
                                    key: "package",
                                    value: { string_value: "<path/to/my/package>" }
                                } 
                            }
                        }
                    }
                }
            }
          }
        }
      }
}

So I guess I'm curious as to whether this was considered / rejected, and if PRs would be welcome here.

We wouldn't want to pollute JsonSchema of course, so I'd suggest this could go through another annotation.

[johanbrandhorst]

Hi Norman, thanks for your issue! I don't remember this having been requested before. I think it could make sense as a feature to save users having to supply these annotations themselves everywhere, but it should be behind a generator option, so it doesn't add annotations to users that don't want it. Would you be interested in helping implement this?

[NPellet]

A generator option would be everything or nothing, though... Oh well I guess it would be enough

But the problem I will hit while doing so is that go-swagger expects the type to implement Validate(formats strfmt.Registry) error (instead of interface-checking at runtime), while [protoc-gen-validate](https://github.com/bufbuild/protoc-gen-validate) provides Validate() error

Ah that's a bit annoying. Not directly related to this issue though. I'll see if I can get go-swagger to assert on the interface instead

[rohitlohar45]

Hi @johanbrandhorst ,

I’d like to contribute to implementing support for x-go-type in the OpenAPI generator. To ensure alignment with the project's requirements, could you help clarify the following?

1. Regarding the generator option approach you mentioned—should this be a global flag, or would it make sense to support more granular control (e.g., per-message or per-package)?
2. Are there any specific concerns about how this might interact with other OpenAPI annotations or existing features?

Additionally, is this feature currently implemented, or does it still need to be worked on? If it's available for contribution, I’d love to help implement it.

Looking forward to your guidance!

Thanks!

[johanbrandhorst]

Hi Rohit, it's great to hear that you'd like to work on implementing this feature. To answer your questions:

1. It should be a global flag, similar to our other generator options. Perhaps something like generate_x_go_type.
2. I think this should be orthogonal to our other options, but it will interact with the global go_package option, assuming that we want to generate an x-go-type annotation matching the generated Go protobuf type.

Some more information for you: It seems like the x-go-type annotation is defined by this example: https://github.com/go-swagger/go-swagger/blob/0477d4a3af47ac446ab3d5d357ab36c03c117b93/fixtures/codegen/existing-model.yml#L99-L103. We'd probably need to support import.package and type. I don't think we should need to support alias. The go_package option should be used as the canonical import path for the generated types (you might be able to set import.package directly to the package value of this option).

Let me know if you need anymore information!

[rohitlohar45]

Thanks @johanbrandhorst for the detailed clarification! Let me summarize my understanding before proceeding:

1. We'll implement this as a global generator option named generate_x_go_type
2. The annotation will use the format from go-swagger's example:

   x-go-type:
     import:
       package: <go_package_value>
     type: <message_name>

3. The go_package option from the proto file will be used directly as the import.package value
4. We won't implement the alias field as it's not needed for this use case

[rohitlohar45]

@johanbrandhorst can you check this PR #5340