search

swaggo / swag

Automatically generate RESTful API documentation with Swagger 2.0 for Go.
MIT License
10.71k stars 1.2k forks source link

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

Open zedongh opened 2 years ago

zedongh commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

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

zedongh commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

ubogdan commented 2 years ago

No active development on this.