Défiition du protocole Swagger jsend

Question

Le protocole Jsend est une simple "norme" sur la façon de formater les réponses json dans une API REST. https://github.com/omniti-labs/jsend

Je génère de la documentation Swagger en utilisant https://github.com/swaggo/swag mais j'ai beaucoup de mal à trouver comment utiliser le format de commentaire déclaratif pour décrire les réponses de Jsend.

Si quelqu'un l'a fait, j'apprécierais beaucoup un exemple de la façon dont il a défini la réponse jsend en utilisant le format de commentaire déclaratif swag.

Answer 1

J'ai résolu ce problème en passant à goswagger.io dont la syntaxe est plus facile à manier. Ce sont les modèles utilisés pour les types de jsend de base. Pour les autres réponses, j'ai remplacé l'élément Data par le nom de la structure pertinente et swagger a fait le reste.

// 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"`
}