Feature Request: Support custom extension fields (x- fields) in Swagger generation from .api file

[ve-weiyi]

What would you like to be added?

I would like to have the ability to add custom extension fields (such as x- prefixed fields) in the generated Swagger/OpenAPI document directly from the .api file.

Why is this needed?

Currently, each endpoint in the .api file can only have a single @doc annotation, which maps to the Swagger description. If I want to mark an endpoint as needing logging, rate limiting, or other metadata, there is no proper way to do it. For example:

@doc "User Login"
@handler Login
post /user/login (LoginRequest) returns (LoginResponse)

If I want to mark this endpoint as requiring logging, the current workarounds are:

1. Pollute the @doc description: Stuff metadata into the single description field, like @doc "User Login [LOG_REQUIRED]". This mixes human-readable descriptions with machine-oriented metadata.

2. Abuse the group field: Create a separate group just for the marker, like "user-log-required". This is too heavyweight for a simple flag.

3. Maintain an external mapping: Keep a separate mapping between endpoints and their metadata in code or config files. This is cumbersome and error-prone.

All of these approaches have significant downsides. The core problems are:

• No semantic annotation mechanism: Cannot intuitively declare endpoint metadata at the definition site
• Not machine-readable: Relying on string parsing or external configuration to convey metadata is fragile and unintuitive
• Poor developer experience: Other frameworks (e.g., go-swagger, swaggo) support annotation-based extension fields, but go-zero does not

Use Cases

The desired outcome is to define structured metadata directly in the .api file that generates Swagger extension fields. For example:

Expected Swagger output:

{
  "paths": {
    "/order/create": {
      "post": {
        "summary": "Create Order",
        "description": "Create a new order",
        "x-log-enabled": true,
        "x-log-type": "business",
        "x-sensitive": true,
        "x-rate-limit": "100/min"
      }
    }
  }
}

This enables downstream automation based on structured extension fields:

• Log middleware automatically enables logging for endpoints marked with x-log-enabled: true
• API gateway auto-configures rate limiting based on x-rate-limit
• Audit systems identify sensitive operations via x-sensitive

Proposed Solution

Introduce a new annotation syntax in the .api file for defining custom extension fields:

Option A: Dedicated annotation keyword

@doc "Create Order"
@x-log-enabled true
@x-log-type business
@x-sensitive true
@handler CreateOrder
post /order/create (CreateOrderRequest) returns (CreateOrderResponse)

Option B: Generic @meta annotation

@doc "Create Order"
@meta log-enabled:true
@meta log-type:business
@meta sensitive:true
@handler CreateOrder
post /order/create (CreateOrderRequest) returns (CreateOrderResponse)

Option C: Block-style declaration

@doc "Create Order"
@metadata {
    log-enabled: true
    log-type: business
    sensitive: true
}
@handler CreateOrder
post /order/create (CreateOrderRequest) returns (CreateOrderResponse)

As long as it supports key:value format custom fields that get generated into Swagger extension fields, the exact syntax can be further discussed.

Additional Context

• Other Go web frameworks (e.g., go-swagger, swaggo) already support similar features via annotations
• This feature would significantly improve the developer experience for teams using go-zero in production, especially for automated middleware configuration and API gateway integration