Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

make swagger comments more readable for go doc #1366

Merged
merged 4 commits into from Oct 28, 2022
Merged

make swagger comments more readable for go doc #1366

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fff2dfb
make swagger comments more readable for go doc
sdghchj Oct 26, 2022
0f6b032
fix unit tests
sdghchj Oct 27, 2022
d8df3a2
update examples
sdghchj Oct 28, 2022
4e16c82
update examples
sdghchj Oct 28, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
4 changes: 2 additions & 2 deletions formatter.go
View file
Open in desktop
Expand Up @@ -107,12 +107,12 @@ func formatFuncDoc(fileSet *token.FileSet, commentList []*ast.Comment, edits *ed
linesToComments := make(map[int]int, len(commentList))

buffer := &bytes.Buffer{}
w := tabwriter.NewWriter(buffer, 0, 0, 1, ' ', 0)
w := tabwriter.NewWriter(buffer, 0, 0, 2, ' ', 0)

for commentIndex, comment := range commentList {
text := comment.Text
if attr, body, found := swagComment(text); found {
formatted := "// " + attr
formatted := "//\t" + attr
if body != "" {
formatted += "\t" + splitComment2(attr, body)
}
Expand Down
132 changes: 66 additions & 66 deletions formatter_test.go
View file
Open in desktop
Expand Up @@ -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/

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

// @host petstore.swagger.io
// @BasePath /v2

// @securityDefinitions.basic BasicAuth

// @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.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.accessCode OAuth2AccessCode
// @tokenUrl https://example.com/oauth/token
// @authorizationurl https://example.com/oauth/authorize
// @scope.admin Grants read and write access to administrative information
// @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

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host petstore.swagger.io
// @BasePath /v2

// @securityDefinitions.basic BasicAuth

// @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.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.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)
Expand All @@ -126,15 +126,15 @@ func Test_FormatMultipleFunctions(t *testing.T) {

want := `package main

// @Produce json
// @Success 200 {object} string
// @Failure 400 {object} string
// @Produce json
// @Success 200 {object} string
// @Failure 400 {object} string
func A() {}

// @Description Description of B.
// @Produce json
// @Success 200 {array} string
// @Failure 400 {object} string
// @Description Description of B.
// @Produce json
// @Success 200 {array} string
// @Failure 400 {object} string
func B() {}`

testFormat(t, "main.go", contents, want)
Expand Down Expand Up @@ -162,17 +162,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)
Expand All @@ -186,9 +186,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`

Expand All @@ -200,8 +200,8 @@ 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
// @Description`
// @Summary Add a new pet to the store
// @Description`

testFormat(t, "empty.go", contents, want)
}
Expand All @@ -211,8 +211,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)

Expand Down