gogo-gingodoc

How to document my service endpoint with goDoc that accepts multipart/form-data


I have a service written in Go/Gin where I accept multipart/form-data to accept a list of files from the user. The code looks like this.

func UploadScreenshotsHandler(c *gin.Context) {
    //Multipart form
    form, err := c.MultipartForm()
    if err != nil {
        logger.Log.Error(err.Error())
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }

    files := form.File
    // more logics with the files
}

I am using GoDoc to document my endpoints. So how do I specify my godoc so that swagger will know this is an endpoint that accepts multipart/form-data?

// UploadFileHandler godoc
// @Summary Upload a list of file 
// @Description An API for clients to upload files
// @Param <WHAT DO I PUT HERE??> <----------
// @Success 200 "Successfully uploaded"
// @Failure 400 {object} interface{} "Bad request: request body has to be form-data"
// @Router / [post]

Solution

  • To specify that the endpoint takes in multiple files

    // UploadFile godoc
    // @Summary Uploads a file
    // @Description Takes in a file as part of a multipart form and stores the file
    // @Tags Uploads
    // @Accept  multipart/form-data
    // @Produce  json
    // @Param file formData file true "File 1 to upload"
    // @Param file1 formData file true "File 2 to upload"
    // @Success 200 "Successfully uploaded"
    // @Failure 400 {object} interface{} "Bad request: request body has to be form-data"
    // @Router / [post]
    
    func UploadHandler(c *gin.Context) {
       ...
    }