如何移除Swagger OpenAPI 2模型定义中的models.包前缀？

问题场景 #

使用swag init为Go Web API生成OpenAPI 2规范时，生成的模型定义自动带上了models.包前缀（如models.Account），不符合仅保留结构体名称（如Account）的需求。

现有API注解 #

// @Summary Get Account
// @Schemes
// @Description Get account data from session token
// @Tags Account
// @Accept json
// @Produce json
// @Success 200 {object} models.Account
// @Router /account [get]
func (h *AccountController) GetAccount(c *gin.Context) {

}

现有模型定义 #

// Account model info
// @Description User account information
// @Description with user id, username, nickname, avatar, roles, guild avatar, and rank
type Account struct {
    ID          string   `json:"id" validate:"required"`
    Username    string   `json:"username" validate:"required"`
    Nick        string   `json:"nick"`
    Avatar      string   `json:"avatar" validate:"required"`
    Roles       []string `json:"roles" validate:"required"`
    GuildAvatar string   `json:"guildAvatar"`
    Rank        string   `json:"rank" validate:"required"`
}

当前生成的模型（带前缀） #

definitions:
  models.Account:
    description: User account information with user id, username, nickname, avatar,
      roles, guild avatar, and rank
    properties:
      avatar:
        type: string
      guildAvatar:
        type: string
      id:
        type: string
      nick:
        type: string
      rank:
        type: string
      roles:
        items:
          type: string
        type: array
      username:
        type: string
    required:
    - avatar
    - id
    - rank
    - roles
    - username
    type: object

预期生成的模型（无前缀） #

definitions:
  Account:
    description: User account information with user id, username, nickname, avatar,
      roles, guild avatar, and rank
    properties:
      avatar:
        type: string
      guildAvatar:
        type: string
      id:
        type: string
      nick:
        type: string
      rank:
        type: string
      roles:
        items:
          type: string
        type: array
      username:
        type: string
    required:
    - avatar
    - id
    - rank
    - roles
    - username
    type: object

解决方法 #

方法一：给结构体添加@name注解 #

在模型结构体的注释中添加// @name 目标名称，强制指定生成的模型名称：

// Account model info
// @Description User account information
// @Description with user id, username, nickname, avatar, roles, guild avatar, and rank
// @name Account
type Account struct {
    ID          string   `json:"id" validate:"required"`
    Username    string   `json:"username" validate:"required"`
    Nick        string   `json:"nick"`
    Avatar      string   `json:"avatar" validate:"required"`
    Roles       []string `json:"roles" validate:"required"`
    GuildAvatar string   `json:"guildAvatar"`
    Rank        string   `json:"rank" validate:"required"`
}

添加后重新执行swag init，生成的模型名称就会变成Account。

方法二：使用swag init的--model-name-strategy参数 #

执行swag init时添加--model-name-strategy simple参数，该参数会自动去掉模型名称中的包前缀，只保留结构体名称：

swag init --model-name-strategy simple

这种方式适合全局批量处理所有模型，无需逐个修改结构体注解。

方法三：配置swaggo全局规则（可选） #

如果需要长期生效，可以在项目根目录创建swag.yaml配置文件，添加以下内容：

parse:
  modelNameStrategy: simple

之后执行swag init时会自动读取该配置，统一处理模型名称。

内容的提问来源于stack exchange，提问作者Blue