From c8fad2caae764a0856fba2e7395a7ba0525b7a0c Mon Sep 17 00:00:00 2001 From: Morre Date: Tue, 20 Dec 2022 21:57:34 +0100 Subject: [PATCH] docs: explain the need for a doc comment when using swag fmt (#1428) --- README.md | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 44e699764..fb4a490df 100644 --- a/README.md +++ b/README.md @@ -316,6 +316,28 @@ Exclude folder： swag fmt -d ./ --exclude ./internal ``` +When using `swag fmt`, you need to ensure that you have a doc comment for the function to ensure correct formatting. +This is due to `swag fmt` indenting swag comments with tabs, which is only allowed *after* a standard doc comment. + +For example, use + +```go +// ListAccounts lists all existing accounts +// +// @Summary List accounts +// @Description get accounts +// @Tags accounts +// @Accept json +// @Produce json +// @Param q query string false "name search by q" Format(email) +// @Success 200 {array} model.Account +// @Failure 400 {object} httputil.HTTPError +// @Failure 404 {object} httputil.HTTPError +// @Failure 500 {object} httputil.HTTPError +// @Router /accounts [get] +func (c *Controller) ListAccounts(ctx *gin.Context) { +``` + ## Implementation Status [Swagger 2.0 document](https://swagger.io/docs/specification/2-0/basic-structure/) @@ -545,20 +567,20 @@ type Account struct { ### Function scoped struct declaration -You can declare your request response structs inside a function body. +You can declare your request response structs inside a function body. You must have to follow the naming convention `.. `. ```go package main -// @Param request body main.MyHandler.request true "query params" +// @Param request body main.MyHandler.request true "query params" // @Success 200 {object} main.MyHandler.response // @Router /test [post] func MyHandler() { type request struct { RequestField string } - + type response struct { ResponseField string }