Swagger OpenAPI 2: Cannot remove package from definition model name

Question

I am generating an OpenAPI 2 Spec for my GoLang Web API via swagger. My generated models all have the package name prefixed before the the model name, which is not the behavior I want.

When I annotate my API as:

// @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) {

}

The models.Account struct comes from my model package, which is defined as:

// 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"`
}

Which produces this definition and name for the model:

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

I would like to be able to produce my model definitions without the package prefix "models." and just have the name of the struct from my GoLang model.

This is the expected model I would want to produce (Removed the prefix "models." from model name):

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

Does anyone know how I can remove the models. prefix from my produced model definitions?

Note, I am using the "swag init" from the swag library to generate the openapi spec: https://github.com/swaggo/swag.

score 1 · Answer 1 · answered Apr 07 '23 at 18:07

I solved my problem by adding an @name annotation to my type and updating my API to reference the new name.

For example, here is my struct now (Notice the @name annotation):

// 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"`
} //@name Account

Here is the API definition updated to reference Account instead of models.Account:

// @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) {

}

This results in a produced definition as:

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

This works for me. There is also a note about this in swaggo ReadMe file here: https://github.com/swaggo/swag#rename-model-to-display — Amit, Aug 30 '23 at 18:44

Swagger OpenAPI 2: Cannot remove package from definition model name

1 Answers1