From 1524e3a0a098a104857f339006e33a849ff313d5 Mon Sep 17 00:00:00 2001 From: Matthieu Moquet Date: Thu, 30 Jun 2022 14:13:10 +0200 Subject: [PATCH] Fix issue https://github.com/swaggo/swag/issues/1150 To summarize the issue, running `swag fmt` will set (at least) 2 spaces between the attribute tag and the rest of the comment. But this is a problem for struct with single comment: ```diff type Example struct { Foobar string -} // @name Example +} // @name Example ``` Indeed the doc generation doesn't interpret this correctly for struct (it completely ignore it). So there are 2 solutions: - fix the indent (which is feel more natural) - fix the doc generation to correctly parse 2 spaces This commit is fixing the indent part. Basically I just set the padding=1 on `tabwriter`. The cons is that it will also impacts all other godocs. For instance (taken from the readme): ```diff -// @title Swagger Example API -// @version 1.0 -// @description This is a sample server celler server. -// @termsOfService http://swagger.io/terms/ +// @title Swagger Example API +// @version 1.0 +// @description This is a sample server celler server. +// @termsOfService http://swagger.io/terms/ ``` --- formatter.go | 2 +- formatter_test.go | 98 +++++++++++++++++++++++------------------------ 2 files changed, 50 insertions(+), 50 deletions(-) diff --git a/formatter.go b/formatter.go index ca3e24c0f..4ad002ebd 100644 --- a/formatter.go +++ b/formatter.go @@ -78,7 +78,7 @@ func formatComments(fileName string, contents []byte, formattedComments []byte, } func formatFuncDoc(commentList []*ast.Comment, formattedComments io.Writer, oldCommentsMap map[string]string) { - w := tabwriter.NewWriter(formattedComments, 0, 0, 2, ' ', 0) + w := tabwriter.NewWriter(formattedComments, 0, 0, 1, ' ', 0) for _, comment := range commentList { text := comment.Text diff --git a/formatter_test.go b/formatter_test.go index 8cc585663..107dbcd33 100644 --- a/formatter_test.go +++ b/formatter_test.go @@ -64,47 +64,47 @@ func Test_FormatMain(t *testing.T) { func main() {}` want := `package main - // @title Swagger Example API - // @version 1.0 - // @description This is a sample server Petstore server. - // @termsOfService http://swagger.io/terms/ + // @title Swagger Example API + // @version 1.0 + // @description This is a sample server Petstore server. + // @termsOfService http://swagger.io/terms/ - // @contact.name API Support - // @contact.url http://www.swagger.io/support - // @contact.email support@swagger.io + // @contact.name API Support + // @contact.url http://www.swagger.io/support + // @contact.email support@swagger.io - // @license.name Apache 2.0 - // @license.url http://www.apache.org/licenses/LICENSE-2.0.html + // @license.name Apache 2.0 + // @license.url http://www.apache.org/licenses/LICENSE-2.0.html - // @host petstore.swagger.io - // @BasePath /v2 + // @host petstore.swagger.io + // @BasePath /v2 - // @securityDefinitions.basic BasicAuth + // @securityDefinitions.basic BasicAuth - // @securityDefinitions.apikey ApiKeyAuth - // @in header - // @name Authorization + // @securityDefinitions.apikey ApiKeyAuth + // @in header + // @name Authorization - // @securitydefinitions.oauth2.application OAuth2Application - // @tokenUrl https://example.com/oauth/token - // @scope.write Grants write access - // @scope.admin Grants read and write access to administrative information + // @securitydefinitions.oauth2.application OAuth2Application + // @tokenUrl https://example.com/oauth/token + // @scope.write Grants write access + // @scope.admin Grants read and write access to administrative information - // @securitydefinitions.oauth2.implicit OAuth2Implicit - // @authorizationurl https://example.com/oauth/authorize - // @scope.write Grants write access - // @scope.admin Grants read and write access to administrative information + // @securitydefinitions.oauth2.implicit OAuth2Implicit + // @authorizationurl https://example.com/oauth/authorize + // @scope.write Grants write access + // @scope.admin Grants read and write access to administrative information - // @securitydefinitions.oauth2.password OAuth2Password - // @tokenUrl https://example.com/oauth/token - // @scope.read Grants read access - // @scope.write Grants write access - // @scope.admin Grants read and write access to administrative information + // @securitydefinitions.oauth2.password OAuth2Password + // @tokenUrl https://example.com/oauth/token + // @scope.read Grants read access + // @scope.write Grants write access + // @scope.admin Grants read and write access to administrative information - // @securitydefinitions.oauth2.accessCode OAuth2AccessCode - // @tokenUrl https://example.com/oauth/token - // @authorizationurl https://example.com/oauth/authorize - // @scope.admin Grants read and write access to administrative information + // @securitydefinitions.oauth2.accessCode OAuth2AccessCode + // @tokenUrl https://example.com/oauth/token + // @authorizationurl https://example.com/oauth/authorize + // @scope.admin Grants read and write access to administrative information func main() {}` testFormat(t, "main.go", contents, want) @@ -132,17 +132,17 @@ func Test_FormatApi(t *testing.T) { import "net/http" - // @Summary Add a new pet to the store - // @Description get string by ID - // @ID get-string-by-int - // @Accept json - // @Produce json - // @Param some_id path int true "Some ID" Format(int64) - // @Param some_id body web.Pet true "Some ID" - // @Success 200 {string} string "ok" - // @Failure 400 {object} web.APIError "We need ID!!" - // @Failure 404 {object} web.APIError "Can not find ID" - // @Router /testapi/get-string-by-int/{some_id} [get] + // @Summary Add a new pet to the store + // @Description get string by ID + // @ID get-string-by-int + // @Accept json + // @Produce json + // @Param some_id path int true "Some ID" Format(int64) + // @Param some_id body web.Pet true "Some ID" + // @Success 200 {string} string "ok" + // @Failure 400 {object} web.APIError "We need ID!!" + // @Failure 404 {object} web.APIError "Can not find ID" + // @Router /testapi/get-string-by-int/{some_id} [get] func GetStringByInt(w http.ResponseWriter, r *http.Request) {}` testFormat(t, "api.go", contents, want) @@ -156,9 +156,9 @@ func Test_NonSwagComment(t *testing.T) { // @ Accept json // This is not a @swag comment` want := `package api - // @Summary Add a new pet to the store - // @Description get string by ID - // @ID get-string-by-int + // @Summary Add a new pet to the store + // @Description get string by ID + // @ID get-string-by-int // @ Accept json // This is not a @swag comment` @@ -170,7 +170,7 @@ func Test_EmptyComment(t *testing.T) { // @Summary Add a new pet to the store // @Description ` want := `package empty - // @Summary Add a new pet to the store + // @Summary Add a new pet to the store // @Description` testFormat(t, "empty.go", contents, want) @@ -181,8 +181,8 @@ func Test_AlignAttribute(t *testing.T) { // @Summary Add a new pet to the store // @Description Description` want := `package align - // @Summary Add a new pet to the store - // @Description Description` + // @Summary Add a new pet to the store + // @Description Description` testFormat(t, "align.go", contents, want)