Swag: Model description tag does not work if model is defined outside of the package

[abdulito]

Describe the bug
I am trying the new description tag field that was introduced by #170 and realized that the "description" tag does not get generated if the struct was defined outside of the package of the package. But it works as expected if the model was defined in the same package of the api.

To Reproduce

// @Success 200 {object} myproject/pkg/api/v1.Post



type Post struct {
    ID int `json:"id" example:"1" format:"int64"`
    // Post name
    Name string `json:"name" example:"poti"`
    // Post data
    Data struct {
        // Post tag
        Tag []string `json:"name"`
    } `json:"data"`
}

Produces this:

    "definitions": {
        "myproject/pkg/api/v1.Post": {
            "type": "object",
            "properties": {
                "data": {
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    }
                },
                "id": {
                    "type": "integer",
                    "format": "int64",
                    "example": 1
                },
                "name": {
                    "type": "string",
                    "example": "poti"
                }
            }
        }
    },

Your swag version
latest from master

Great tool btw. Thanks!

[artuross]

I believe this will work only if you import package containing the struct you're referring to. Import the package for side-effects (using _ before the package path in imports statement) or simply declare a variable with type so the package will get imported.

[t-evers]

I tried it with project path or only latest package in path dot model. In both cases I get an error:
2018/08/17 14:57:50 ParseComment panic:can not parse response comment "200 {object} project1/types.ResponseObject response" panic: ParseComment panic:can not parse response comment "200 {object} project1/types.ResponseObject response"

I created a testcase as small as possible to reproduce the problem
testcase-project.zip

We have several projects with common data structures to be used. So there is everytime a project with a package containing those data models which is then used by other projects which process or serve them.

swag is a great tool and I would really like to include it in our automatic build process to have the documentation build everytime the project is build. But with projects having other projects as dependency there is this problem left.

[dselans]

@t-evers the issue you're referencing should be solved by #189

[t-evers]

Did a "go get -u github.com/swaggo/swag" today and tried but the result is still the same:
can not parse response comment "200 {object} project1/types.ResponseObject"

[dselans]

@t-evers what is project1/ in types.ResponseObject? You should be importing the pkg types (from wherever it is) and referencing it in the comment as just types.ResponseObject.

Note if you do not actually use types.ResponseObject within the handler itself, just make a dummy use of it (so that the import is allowed), such as:

var (
    _ = types.ResponseObject{}
)

Here's a full example of a spec handler that references an external pkg (that is vendored):

// @Summary Greets you with a friendly message
// @Description If this endpoint does not work, something is seriously busted
// @Tags basic
// @Produce json
// @Success 200 {object} rye.JSONStatus "The service was able to start enough to be able to service inbound requests"
// @Router / [get]
func (a *API) homeHandler(rw http.ResponseWriter, r *http.Request) {
    rye.WriteJSONStatus(rw, "Oh, hello there!", "Refer to README.md for API usage", http.StatusOK)
}

Good luck.

[t-evers]

@dselans project1 is the project, types.ResponseObject is defined in (see the testcase I provided).
According to your hint I changed that to simply types.ResponseObject but the resutt is still the same:

2018/08/21 09:14:33 ParseComment panic:can not parse response comment "200 {object} types.ResponseObject"
panic: ParseComment panic:can not parse response comment "200 {object} types.ResponseObject"

[8tomat8]

Have the same problem on v1.4.0.
@t-evers As a workaround, you can try to use project with the standard structs as a git submodule of your main project.

[easonlin404]

Please use the latest swag that supports external package via #415.

[pjebs]

Still doesn't work (when using aliases for imports).

[sabau]

I'm having the same problem, a dirty workaround that I would like to avoid, just to make it produce the basic swagger.yaml, is to use the whole path instead of the alias, in my case:

import (
    ctypes "github.com/tendermint/tendermint/rpc/core/types"
...

// @Summary Get Node health
// @Description 200 if succesful, no response in case of errors
// @Produce json
// @Success 200 {object} github.com/tendermint/tendermint/rpc/core/types.ResultHealth "Node status"
// @Router /health [get]
func Health( ...

but the resulting file is not really telling me much about the data

  /health:
    get:
      description: Get node health. Returns empty result (200 OK) on success, no response
        in case of an error
      produces:
      - application/json
      responses:
        "200":
          description: result will be empty
          schema:
            $ref: '#/definitions/github.com/tendermint/tendermint/rpc/core/types.ResultHealth'
            type: object
      summary: Get node health

[Chemasmas]

Hello, this problem stills persist, i have tried the @dselans hint

My code is next

models package
`package models

import (
"go.mongodb.org/mongo-driver/bson/primitive"
)

type User struct {
ID primitive.ObjectID json:"id" bson:"_id"
Email string json:"email" bson:"email"
Password string json:"password" bson:"password"
}`

and the handler is some like this

// Register User // @Sumary Metodo de Registro de Usuario // @Description Registra un usuario // @Tags Status // @Param account body User true "Add account" // @Accept json // @Produce json // @Success 200 {object} User // @Failure 400 {string} string "" // @Failure 500 {string} string "MarShallingError" // @Router /user/register [POST] func Register(w http.ResponseWriter, r *http.Request) { var user User defer r.Body.Close() ...

the given result, has the model in the swagger, but no definition

"parameters": [ { "description": "Add account", "name": "account", "in": "body", "required": true, "schema": { "type": "object", "$ref": "#/definitions/User" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "$ref": "#/definitions/User" } }, "400": { "description": "Bad Request", "schema": { "type": "string" } }, "500": { "description": "MarShallingError", "schema": { "type": "string" } } }

not in the param or the result