swag icon indicating copy to clipboard operation
swag copied to clipboard

Published 20 hours ago • verified publisher icon swaggo

swag init generates empty paths/routes with v1.8.3 onwards

Open owais1412 opened this issue 1 year ago • 16 comments

Describe the bug Not able to generate swagger files for my project. Tried swag init --parseDependency -g main.go as well. Still the same. Only these lines are outputted in the console.

create docs.go at docs/docs.go
create swagger.json at docs/swagger.json
create swagger.yaml at docs/swagger.yaml

It works fine with version v1.8.2 and below.

Your swag version swag v1.8.3 and onwards

Your go version Go 1.19.3

owais1412 avatar Jul 07 '23 10:07 owais1412

Same problem here.

Project structure:

project |-- cmd | |-- server | |-- main.go |-- server |-- server.go

main function is importing a StartServer function from the server package, where the router is settled.

The question is: how swaggo is parsing the server endpoints?

AxelRHD avatar Jul 11 '23 00:07 AxelRHD

Same problem here.

Project structure:

project |-- cmd | |-- server | |-- main.go |-- server |-- server.go

main function is importing a StartServer function from the server package, where the router is settled.

The question is: how swaggo is parsing the server endpoints?

swag init -g ./cmd/main.go -d ./server

sdghchj avatar Jul 17 '23 08:07 sdghchj

Same problem here. Project structure: project |-- cmd | |-- server | |-- main.go |-- server |-- server.go main function is importing a StartServer function from the server package, where the router is settled. The question is: how swaggo is parsing the server endpoints?

swag init -g ./cmd/main.go -d ./server

That doesn't work either swag init -g ./cmd/server/main.go -d ./server

Got this error:

2023/07/17 21:03:17 Generate swagger docs....
2023/07/17 21:03:17 Generate general API Info, search dir:./server
2023/07/17 21:03:17 cannot parse source files /home/axelr/go-projects/swagger-chi-playground/server/cmd/server/main.go: open /home/axelr/go-projects/swagger-chi-playground/server/cmd/server/main.go: no such file or directory

The resolution of the folder structure is incorrect.

AxelRHD avatar Jul 17 '23 19:07 AxelRHD

Same issue here, project structure :

├── README.md
├── controllers
│   ├── bozo-coin.go
│   ├── controller.go
│   ├── default-route.go
│   └── user.go
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── go.mod
├── go.sum
├── license
├── main.go
├── metrics
│   ├── bozo-coin.go
│   └── metrics.go
├── models
│   ├── bozo-coin.go
│   ├── models.go
│   └── user.go
└── utils
    ├── db-connection.go
    ├── error.go
    └── message.go

Go version : 1.18.10 (also tried in 1.20.1 and 1.17.10) Swag version 1.8.10

Output json :

{
    "swagger": "2.0",
    "info": {
        "description": "A Bozo coin management service API in Go using Gin framework, storing data in PostgreSQL and using Prometheus for metrics.",
        "title": "Bozo API",
        "contact": {
            "name": "Bozo Support",
            "url": "https://danstonkube.fr",
            "email": "[email protected]"
        },
        "license": {
            "name": "Apache 2.0",
            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
        },
        "version": "1.0"
    },
    "basePath": "/api/v1",
    "paths": {}
}

Obtained by running :

swag init --pd -g main.go

panzouh avatar Jul 24 '23 14:07 panzouh

In my case empty paths were due to runtime.GOROOT() producting an empty string (and, I believe, since swag ignores all paths with runtime.GOROOT() prefix, it ignored all of them). The reason runtime.GOROOT() would be empty could be b/c of the way swag is built. In my case it was a nix package, with this issue: https://github.com/NixOS/nixpkgs/issues/224701

d-honeybadger avatar Jul 26 '23 22:07 d-honeybadger

I am adding more context b/c it could be related :

❯  swag init --pd
2023/07/27 14:22:36 Generate swagger docs....
2023/07/27 14:22:36 Generate general API Info, search dir:./
2023/07/27 14:22:38 warning: failed to evaluate const locb at /Users/panz/go/1.18.10/pkg/mod/github.com/pelletier/go-toml/[email protected]/internal/characters/utf8.go:183:2, strconv.ParseUint: parsing "b10000000": invalid syntax
2023/07/27 14:22:38 warning: failed to evaluate const hicb at /Users/panz/go/1.18.10/pkg/mod/github.com/pelletier/go-toml/[email protected]/internal/characters/utf8.go:184:2, strconv.ParseUint: parsing "b10111111": invalid syntax
2023/07/27 14:22:40 create docs.go at docs/docs.go
2023/07/27 14:22:40 create swagger.json at docs/swagger.json
2023/07/27 14:22:40 create swagger.yaml at docs/swagger.yaml

Issue on this repo

In my case empty paths were due to runtime.GOROOT() producting an empty string (and, I believe, since swag ignores all paths with runtime.GOROOT() prefix, it ignored all of them). The reason runtime.GOROOT() would be empty could be b/c of the way swag is built. In my case it was a nix package, with this issue: NixOS/nixpkgs#224701

package main

import (
	"flag"
	"fmt"
	"log"
	"net/http"
	"runtime"

	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	"gitlab.com/panzouh/bozo-api/controllers"
	"gitlab.com/panzouh/bozo-api/docs"
)

func main() {
	address := flag.String("address", ":", "address to listen on")
	port := flag.String("port", "3000", "port to listen on")
	// Truncated
	appRouter := gin.Default()
	// programmatically set swagger info
	docs.SwaggerInfo.Title = "Bozo API"
	docs.SwaggerInfo.Description = "A REST API for the Bozo app using Gin and GORM, PostgreSQL, and Prometheus."
	docs.SwaggerInfo.Version = "1.0"
	docs.SwaggerInfo.Host = *address + *port
	docs.SwaggerInfo.BasePath = "/api/v1"

	// Truncated
	// Set swagger route
	appRouter.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

	//fmt Print runtime goroot
	fmt.Println(runtime.GOROOT())

	// Truncated
	// Run the app server
	err := appRouter.Run(*address + *port)
	if err != nil {
		panic(err)
	}
}

❯ go run main.go
/Users/panz/.goenv/versions/1.18.10

panzouh avatar Jul 27 '23 12:07 panzouh

Any updates?

owais1412 avatar Aug 09 '23 08:08 owais1412

I have this issue as well, the paths block is empty, even though I've added a section to (minimally) describe it:

// handleNewToken godoc // @Summary Create New Token // @ID new-token // @Accept json // @Produce json // @Success 200 // @Failure 404 // @Router /newToken [post] func handleNewToken(s *Server) http.HandlerFunc {

The title and version info are created in the generated swagger.json, but the paths entry is empty. My GoRoot is set (/usr/local/go) and this application is not in that path, so it should not be skipped.

I do also get the invalid syntax that I see some other folks posting when I run with --pd:

swag init --pd 2023/08/09 12:18:21 Generate swagger docs.... 2023/08/09 12:18:21 Generate general API Info, search dir:./ 2023/08/09 12:18:22 warning: failed to evaluate const locb at /home/abc/gocode/pkg/mod/github.com/pelletier/go-toml/[email protected]/internal/characters/utf8.go:183:2, strconv.ParseUint: parsing "b10000000": invalid syntax 2023/08/09 12:18:22 warning: failed to evaluate const hicb at /home/abc/gocode/pkg/mod/github.com/pelletier/go-toml/[email protected]/internal/characters/utf8.go:184:2, strconv.ParseUint: parsing "b10111111": invalid syntax 2023/08/09 12:18:22 create docs.go at docs/docs.go 2023/08/09 12:18:22 create swagger.json at docs/swagger.json 2023/08/09 12:18:22 create swagger.yaml at docs/swagger.yaml

blcpeck avatar Aug 09 '23 19:08 blcpeck

Posting an update since I somehow figured how to generate documentation, it seems that including my controller directory and persist dependencies affected swag's behavior :

❯ swag init -g main.go --pd -d ./,./controllers
2023/08/17 14:36:38 Generate swagger docs....
2023/08/17 14:36:38 Generate general API Info, search dir:./
2023/08/17 14:36:38 Generate general API Info, search dir:./controllers
2023/08/17 14:36:40 warning: failed to evaluate const locb at /Users/panz/go/1.20.1/pkg/mod/github.com/pelletier/go-toml/[email protected]/internal/characters/utf8.go:183:2, strconv.ParseUint: parsing "b10000000": invalid syntax
2023/08/17 14:36:40 warning: failed to evaluate const hicb at /Users/panz/go/1.20.1/pkg/mod/github.com/pelletier/go-toml/[email protected]/internal/characters/utf8.go:184:2, strconv.ParseUint: parsing "b10111111": invalid syntax
2023/08/17 14:36:40 Generating utils.HTTPError
2023/08/17 14:36:40 Generating controllers.FindBozoCoinResponse
2023/08/17 14:36:40 Generating models.BozoCoin
2023/08/17 14:36:40 Generating gorm.Model
2023/08/17 14:36:40 Generating gorm.DeletedAt
2023/08/17 14:36:40 Generating sql.NullTime
2023/08/17 14:36:40 Generating utils.Message
2023/08/17 14:36:40 Generating models.CreateBozoCoinInput
2023/08/17 14:36:40 Generating controllers.CreateBozoCoinResponse
2023/08/17 14:36:40 Generating models.DeleteBozoCoinInput
2023/08/17 14:36:40 Generating controllers.DeleteBozoCoinResponse
2023/08/17 14:36:40 Generating controllers.FindGroupsResponse
2023/08/17 14:36:40 Generating models.Group
2023/08/17 14:36:40 Generating models.User
2023/08/17 14:36:40 Generating models.ReverseBozoCoin
2023/08/17 14:36:40 Generating models.UserAchievement
2023/08/17 14:36:40 Generating models.CreateGroupInput
2023/08/17 14:36:40 Generating controllers.CreateGroupResponse
2023/08/17 14:36:40 Generating controllers.DeleteGroupResponse
2023/08/17 14:36:40 Generating controllers.LivenessResponse
2023/08/17 14:36:40 Generating models.AdminUserLoginInput
2023/08/17 14:36:40 Generating controllers.LoginResponse
2023/08/17 14:36:40 Generating controllers.ReadinessResponse
2023/08/17 14:36:40 Generating controllers.FindReverseBozoCoinResponse
2023/08/17 14:36:40 Generating models.CreateReverseBozoCoinInput
2023/08/17 14:36:40 Generating controllers.CreateReverseBozoCoinResponse
2023/08/17 14:36:40 Generating models.DeleteReverseBozoCoinInput
2023/08/17 14:36:40 Generating controllers.DeleteReverseBozoCoinResponse
2023/08/17 14:36:40 Generating controllers.FindUsersResponse
2023/08/17 14:36:40 Generating models.CreateUserInput
2023/08/17 14:36:40 Generating controllers.CreateUserResponse
2023/08/17 14:36:40 Generating controllers.DeleteUserResponse
2023/08/17 14:36:40 create docs.go at docs/docs.go
2023/08/17 14:36:40 create swagger.json at docs/swagger.json
2023/08/17 14:36:40 create swagger.yaml at docs/swagger.yaml

This warning may be irrelevent warning: failed to evaluate const locb at /Users/panz/go/1.20.1/pkg/mod/github.com/pelletier/go-toml/[email protected]/internal/characters/utf8.go:183:2, strconv.ParseUint: parsing "b10000000": invalid syntax

Sample controller func :

type FindGroupsResponse struct {
	Data []models.Group `json:"data"`
}

// FindGroups godoc
//
//	@Summary		Find Groups
//	@Description	Retrieve a list of all groups along with their associated users.
//	@Tags			Groups
//	@Accept			json
//	@Produce		json
//	@Success		200	{object}	FindGroupsResponse
//	@Failure		400	{object}	utils.HTTPError
//	@Failure		500	{object}	utils.HTTPError
//	@Router			/groups [get]
func (c *Controller) FindGroups(ctx *gin.Context) {
	var groups []models.Group
	if err := c.Database.Preload("Users").Find(&groups).Error; err != nil {
		utils.NewError(ctx, 500, err)
		return
	}

	// Append Group data to to FindGroupsResponse
	var response FindGroupsResponse
	response.Data = groups

	// Return group data
	ctx.JSON(200, response)
}

panzouh avatar Aug 17 '23 12:08 panzouh

Same issue here, project structure :

├── README.md
├── controllers
│   ├── bozo-coin.go
│   ├── controller.go
│   ├── default-route.go
│   └── user.go
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── go.mod
├── go.sum
├── license
├── main.go
├── metrics
│   ├── bozo-coin.go
│   └── metrics.go
├── models
│   ├── bozo-coin.go
│   ├── models.go
│   └── user.go
└── utils
    ├── db-connection.go
    ├── error.go
    └── message.go

Go version : 1.18.10 (also tried in 1.20.1 and 1.17.10) Swag version 1.8.10

Output json :

{
    "swagger": "2.0",
    "info": {
        "description": "A Bozo coin management service API in Go using Gin framework, storing data in PostgreSQL and using Prometheus for metrics.",
        "title": "Bozo API",
        "contact": {
            "name": "Bozo Support",
            "url": "https://danstonkube.fr",
            "email": "[email protected]"
        },
        "license": {
            "name": "Apache 2.0",
            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
        },
        "version": "1.0"
    },
    "basePath": "/api/v1",
    "paths": {}
}

Obtained by running :

swag init --pd -g main.go

I have the same problem

PauloYR avatar Aug 17 '23 17:08 PauloYR

Mitrate to version 1.7.0

Work to me

2023/08/17 14:35:10 Generate swagger docs.... 2023/08/17 14:35:10 Generate general API Info, search dir:./ 2023/08/17 14:35:11 Generating model.PayLoadData 2023/08/17 14:35:11 create docs.go at docs/docs.go 2023/08/17 14:35:11 create swagger.json at docs/swagger.json 2023/08/17 14:35:11 create swagger.yaml at docs/swagger.yaml

go clean -i github.com/swaggo/swag/cmd/swag go install github.com/swaggo/[email protected]

PauloYR avatar Aug 17 '23 17:08 PauloYR

Mitrate to version 1.7.0

Work to me

2023/08/17 14:35:10 Generate swagger docs.... 2023/08/17 14:35:10 Generate general API Info, search dir:./ 2023/08/17 14:35:11 Generating model.PayLoadData 2023/08/17 14:35:11 create docs.go at docs/docs.go 2023/08/17 14:35:11 create swagger.json at docs/swagger.json 2023/08/17 14:35:11 create swagger.yaml at docs/swagger.yaml

go clean -i github.com/swaggo/swag/cmd/swag go install github.com/swaggo/[email protected]

Mine works if I downgrade to v1.8.2 or less. But v1.8.3 onwards the swag build time is improved. The point is to able to use the latest versions.

owais1412 avatar Aug 18 '23 15:08 owais1412

I think I was running into a similar thing and it turned out that I was adding an extra space or newline in between my doc comments and my function definition. at least for me that seemed to be the issue and just posting in case this helps

rohodo avatar Oct 22 '23 05:10 rohodo

Mitrate to version 1.7.0 Work to me

2023/08/17 14:35:10 Generate swagger docs.... 2023/08/17 14:35:10 Generate general API Info, search dir:./ 2023/08/17 14:35:11 Generating model.PayLoadData 2023/08/17 14:35:11 create docs.go at docs/docs.go 2023/08/17 14:35:11 create swagger.json at docs/swagger.json 2023/08/17 14:35:11 create swagger.yaml at docs/swagger.yaml

go clean -i github.com/swaggo/swag/cmd/swag go install github.com/swaggo/[email protected]

Mine works if I downgrade to v1.8.2 or less. But v1.8.3 onwards the swag build time is improved. The point is to able to use the latest versions.

I encountered the same problem, and when I introduced the vendor dependency in main.go, the generation speed changed from one minute to one second.

linliyuan avatar Dec 13 '23 07:12 linliyuan

In my case empty paths were due to runtime.GOROOT() producting an empty string (and, I believe, since swag ignores all paths with runtime.GOROOT() prefix, it ignored all of them). The reason runtime.GOROOT() would be empty could be b/c of the way swag is built. In my case it was a nix package, with this issue: NixOS/nixpkgs#224701

I'm using go-swag from nixpkgs and I had the same problem, as a workaround I'm invoking swag with:

(source <(go env) && swag init)

in my Makefile.

evan-goode avatar Feb 23 '24 21:02 evan-goode

Same at my end with 1.16.3.

Is there any solution to it? I am using the go-chi router.

Thanks

GirishBhutiya avatar Apr 24 '24 08:04 GirishBhutiya