[Question] Why comment on interface method not be parsed?

[zedongh]

For interface and implementation seperation, doc comment on interface not concrete implementation should be a right choice. But i find swag not parse, how it works?

Here is my code: (comment on concrete implementation works)

type HealthProbeController interface {
	// Ping godoc
	// @Summary Server health probe
	// @Description server running health check
	// @Tags probe
	// @Produce json
	// @Success 200 {object} PingResponse
	// @Router /api/v1/ping [get]
	Ping(c *gin.Context)
}

[zedongh]

For interface and implementation seperation, doc comment on interface not concrete implementation should be a right choice. But i find swag not parse, how it works?

Here is my code: (comment on concrete implementation works)

type HealthProbeController interface {
	// Ping godoc
	// @Summary Server health probe
	// @Description server running health check
	// @Tags probe
	// @Produce json
	// @Success 200 {object} PingResponse
	// @Router /api/v1/ping [get]
	Ping(c *gin.Context)
}

It's seems refer to parser.go

// ParseRouterAPIInfo parses router api info for given astFile.
func (parser *Parser) ParseRouterAPIInfo(fileName string, astFile *ast.File) error {
	for _, astDescription := range astFile.Decls {
		astDeclaration, ok := astDescription.(*ast.FuncDecl)
		if ok && astDeclaration.Doc != nil && astDeclaration.Doc.List != nil {
        ....
}

only handle astFile.Decl match *ast.FuncDeclcase

[ubogdan]

@zedongh Interface declarations cannot be used as response definitions/values. We don't mind being more flexible here but we need to implement this in such a way it returns a value from it.

[zedongh]

values

interface method defined input argement and return values much better.

Buf for gin web framework handler, the return value always be void, response always be put into *gin.Context, so @Success 200 {object} PingResponse comment is same need for interface way and implementation way.

[ubogdan]

@zedongh did you tried?

// Ping godoc
// @Summary Server health probe
// @Description server running health check
// @Tags probe
// @Produce json
// @Success 200 {object} PingResponse
// @Router /api/v1/ping [get]
type HealthProbeController interface {
	Ping(c *gin.Context)
}

[ubogdan]

swag generator expects the route comment to be placed in the main document, not in the type declaration.

[zedongh]

declaration

@zedongh did you tried?

// Ping godoc
// @Summary Server health probe
// @Description server running health check
// @Tags probe
// @Produce json
// @Success 200 {object} PingResponse
// @Router /api/v1/ping [get]
type HealthProbeController interface {
	Ping(c *gin.Context)
}

Yeah, I tried. General info will be parsed, but router api comment only be parsed when it commented on function type.

[ubogdan]

declaration

@zedongh did you tried?

// Ping godoc
// @Summary Server health probe
// @Description server running health check
// @Tags probe
// @Produce json
// @Success 200 {object} PingResponse
// @Router /api/v1/ping [get]
type HealthProbeController interface {
	Ping(c *gin.Context)
}

Yeah, I tried. General info will be parsed, but router api comment only be parsed when it commented on function type.

That's true, see source code.

[Luna-CY]

Are there any new developments on this issue? Has it been explicitly rejected or is there a plan for it?

[ubogdan]

No active development on this.