0

I have some problem. In different sites you can find how to correctly describe go struct using swagger(annotations). Example:

// swagger:model
type User struct {
    // the id for this user
    //
    // required: true
    // min: 1
    ID int64 `json:"id"`

    // the name for this user
    // required: true
    // min length: 3
    Name string `json:"name"`
}

But can someone help me with, how to describe go struct that is in the method and isn't public? And what I should to enter in @Param field after description for successful generation docs? Example:

func (n *newStruct) GetPetInfo(c *gin.Context){
info := struct {
    PetId  uint64 `form:"petId" json:"petId"`
    Sl     uint64 `form:"sl" json:"sl"`
}{}

...

}

Help me please with this situation)

Gringo
  • 1

1 Answers1

-1

To document a Go struct that is not public, you can still use Swagger annotations by placing them as comments above the struct definition. However, keep in mind that Swagger will not generate documentation for non-public structs.

For the GetPetInfo method, you can use the @Param annotation to describe the parameters expected by the method. Here's an example of how you could annotate the method:

// GetPetInfo gets information about a pet.
//
// @Summary Get pet info
// @Description Retrieves information about a pet given its ID and SL.
// @ID get-pet-info
// @Param petId query uint64 true "The ID of the pet"
// @Param sl query uint64 true "The SL of the pet"
// @Success 200 {object} PetInfoResponse
// @Failure 404 {object} ErrorResponse
// @Router /pet-info [get]
func (n *newStruct) GetPetInfo(c *gin.Context){
    info := struct {
        PetId  uint64 `form:"petId" json:"petId"`
        Sl     uint64 `form:"sl" json:"sl"`
    }{}

    // ...
}

In this example, the @Param annotation is used to describe the expected query parameters for the method. The first argument specifies the name of the parameter (petId and sl), followed by the location of the parameter (query), the data type (uint64), whether the parameter is required (true), and finally a description of the parameter.

You can adjust the details in the @Param annotation based on your requirements. Note that you'll need to replace PetInfoResponse and ErrorResponse with the appropriate response models for your API.

Morteza Dehghani mrtdeh
  • 19
  • 1
  • 4
  • 2
    This appears likely to have been written (entirely or partially) by AI (e.g., ChatGPT). If you used an AI tool to assist with any answer, I would encourage you to delete it, as [posting of AI-generated content is banned here](//meta.stackoverflow.com/q/421831). **Readers should review this answer carefully and critically, as AI-generated information often contains fundamental errors and misinformation.** If you observe quality issues and/or have reason to believe that this answer was AI-generated, please leave feedback accordingly. The moderation team can use your help to identify issues. – NotTheDr01ds Jun 13 '23 at 10:32