`openapiv3`: Custom Annotations

Author: aidandjCreated Apr 16, 2026Updated Apr 21, 2026
LabelsOpenAPI v3

Feature

Custom annotations allow overriding a variety of aspects of the generated code. Extension 1295 has been registered for v3 annotations.

I'll list a few common use cases, and we can prioritize and check them off as we go (moved to sub-issues).

Additionally something I'd like to explore, is referencing proto messages in annotations. For example, a custom error response code, with a custom schema, but instead of defining the schema with the custom annotations, reference a proto message.

      responses: {
        key: "207"
        value: {
          description: "Mixed response."
          schema: {
            proto_message: {ref: ".api.responses.v1.MixedResponse"}
          }
        }
      }

Please add a if this feature is useful/required for you.

Source: grpc-ecosystem/grpc-gateway