How to exclude fields with json tags when documenting query parameters?

[shjhwoo]

1. 🧐 The Problem Statement

I am encountering an issue when trying to use a single DTO struct for both API request bodies and query parameters in a Go backend service, which affects the generated Swagger documentation.

When I define a DTO structure that contains fields tagged for both JSON (json:"...") and Query/Form (form:"..." or just query in Swaggo annotations), Swaggo treats all fields, including the json-only fields, as valid query parameters in the generated documentation.

2. 🧑‍💻 Example Scenario

Consider the following DTO used in a controller:

type UnifiedRequest struct {
    // Should be a Query Parameter
    QueryID string `form:"query_id" binding:"required"` 

    // Should ONLY be in the Request Body (JSON)
    BodyData string `json:"body_data" binding:"required"`
}

If I use this UnifiedRequest for documenting a GET endpoint's query parameters:

// @Param request query UnifiedRequest true "User ID and some body data"
// @Router /api/endpoint [get]

Actual Result: The generated Swagger UI shows both QueryID and BodyData as available query parameters, which is incorrect for the production API logic (as BodyData should never be a query param).

3. 🤔 Questions & Seeking Guidance

This leads to two key design questions regarding both Go DTO best practices and Swaggo's intended usage:

1. Is this the intended behavior? Is it assumed that developers will always adhere to the Single Responsibility Principle (SRP) and strictly separate DTOs (e.g., QueryDTO and BodyDTO) to prevent this type of conflict?
2. Potential for Improvement: Are there any plans, or would the maintainers consider, an enhancement to automatically exclude fields tagged with json:"..." when documenting parameters as query?
   • e.g., A new tag like swaggotag:"exclude_if_query" or a conditional parsing logic.

I believe adding an exclusion mechanism would provide flexibility for teams that prefer DTO consolidation, but I understand the argument for maintaining strict SRP. I would appreciate any insight into the project's philosophy on this matter.

Thank you for your time and for maintaining Swaggo!

[sdghchj]

Now it does not support, since json tag is only used to determine the default name of a form/header/uri parameter,
PR is welcome.
A recomended way as below, explicitly set form:"-".

type UnifiedRequest struct {
    // Should be a Query Parameter
    QueryID string `form:"query_id" binding:"required"` 

    // Should ONLY be in the Request Body (JSON)
    BodyData string `json:"body_data" form:"-" binding:"required"`

PR:

// https://github.com/swaggo/swag/blob/v1.16.6/operation.go#L327
if nameVal, ok := item.Schema.Extensions.GetString(nameOverrideType); ok {
	name = nameVal
	if name == "-" {
		continue
	}
}