swagger - jsend 协议 Swagger 定义

Question

Jsend 协议是如何在 REST API 中格式化 json 响应的简单“标准”。https://github.com/omniti-labs/jsend

我正在使用https://github.com/swaggo/swag生成 Swagger 文档，但是在弄清楚如何使用声明性评论格式来描述 Jsend 响应时遇到了很大的麻烦。

如果有人这样做，我将非常感谢他们如何使用 swag 声明性注释格式定义 jsend 响应的示例片段。

Answer 1

我通过切换到更易于处理语法的goswagger.io解决了这个问题。这些是用于基本 jsend 类型的模型。对于其他响应，我将 Data 元素替换为相关结构的名称，其余部分由 swagger 完成。

// Success: no response data required
// swagger:response responseSuccess
type responseSuccess struct {
    // in: body
    Body struct {
        // enum: success
        Status string      `json:"status"`
        Data   interface{} `json:"data"`
    } `json:"body"`
}

// Error: Incorrect use of the API or the requested data is not available
// swagger:response responseError
type responseError struct {
    // in: body
    Body struct {
        // enum: error
        Status  string      `json:"status"`
        Data    interface{} `json:"data"`
        Message string      `json:"message"`
    } `json:"body"`
}

// Fail: Backend or system failure.
// swagger:response responseFail
type responseFail struct {
    // in: body
    Body struct {
        // enum: fail
        Status  string      `json:"status"`
        Data    interface{} `json:"data"`
        Message string      `json:"message"`
    } `json:"body"`
}