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.

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

Overwrite Interface with specific type in response annotation #2596

Open
katexochen opened this issue Jun 30, 2021 · 1 comment
Open

Overwrite Interface with specific type in response annotation #2596

katexochen opened this issue Jun 30, 2021 · 1 comment
Labels
generate spec Related to spec generation from code scanner

Comments

@katexochen
Copy link

Problem statement

I am trying to annotate an existing API in JSend style. The following struct represents the structure of every API response:

package server
type GeneralResponse struct {
	Status  string      `json:"status"`
	Data    interface{} `json:"data"`
	Message string      `json:"message,omitempty"` // only used when status = "error"
}

Handlers return this struct with a specific stuct in the Data interface, e.g., the getStatus handler retruns a GeneralResponse with a StatusResp as Data:

package server
type StatusResp struct {
	StatusCode int
	StatusMessage string
}

How can I annotate my code in such a way, that the model of my response is a GeneralResponse containing a StatusResp?
Swaggo/swag let you overwrite the interface with a specific type. Is there a way to do something similar for go-swagger?

There are some related Issues: #619, #1708
In #619 (comment), @casualjim suggests to have a look at the allOf and discriminated functions, but as far as I understood those, they are not solving this problem, since I don't want multiple possible values of Data, but one specific.

This is my current state:

// swagger:route GET /status status statusGet
//
// ...
//
//     Responses:
//       200: StatusResponse

// swagger:response StatusResponse
type StatusResponse struct {
	// in:body
	Body struct {
		// example: success
		Status string
		Data   server.StatusResp
	}
}

This is close to what I want, but has the following problems:

  • The response does not have the GeneralResponse type/model
  • I would have to rewrite this for every response

It would be nice to do it like this:

// swagger:route GET /status status statusGet
//
// ...
//
//     Responses:
//       200: body:GeneralResponse{Data: StatusResponse}

Environment

swagger version: v0.27.0
go version: 1.14
OS: Ubuntu 18.04 LTS

@katexochen
Copy link
Author

katexochen commented Jul 1, 2021

The resulting Spec should look somewhat like this:

      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/server.GeneralResponse'
            - properties:
                data:
                  $ref: '#/definitions/server.StatusResp'
              type: object

@fredbi fredbi added scanner generate spec Related to spec generation from code labels Dec 22, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
generate spec Related to spec generation from code scanner
Projects
None yet
Development

No branches or pull requests

2 participants