web-dev-qa-db-fra.com

Modèle de réponse pour des codes d'état spécifiques à l'aide de Swagger

J'utilise Swagger pour documenter mon REST (utilisant asp.net web api 2). Existe-t-il un moyen dans swagger de donner des modèles de réponse pour chaque réponse possible pour un appel api donné? J'annote la réponse du code d'état en utilisant les commentaires xml comme ceci:

    /// <summary>
    /// Save a person
    /// </summary>
    /// <response code="200">Ok</response>
    /// <response code="400">Bad Request</response>
    /// <response code="500">Internal Server error</response>
    public HttpResponseMessage SavePerson() {...}

enter image description here

c#restasp.net-web-apiswagger
18
Kaladin

Vous pouvez essayer d'utiliser cref = "TYPE HERE" sur vos commentaires XML comme celui-ci.

/// <response code="400" cref="CustomErrorModel">Bad Request</response>

Mais je suggérerais d'utiliser les annotations que Swagger vous donne.

[SwaggerResponse(HttpStatusCode.OK, Type = typeof(OnlineMerchantQueryResponseInformation))]

attribuez cela à vos contrôleurs.

34
EvilToaster101

Votre signature indique que vous retournez un HttpResponseMessage, pas un modèle de données. Si vous renvoyez un IActionResult et que vous utilisez ASP.NET Core, vous pouvez utiliser l'attribut "ProducesResponseType":

[ProducesResponseType(typeof(IEnumerable<YourModel>), 200)]

ProducesResponsesType se trouve dans l'espace de noms Microsoft.AspNetCore.Mvc.

Voir https://github.com/domaindrivendev/Swashbuckle.AspNetCore#list-operation-responses "Réponses explicites"

15
Elton

Si vous utilisez Swashbuckle, vous pouvez essayer

 [SwaggerResponse(200, typeof(CustomModel))]

et vous ajoutez en outre un commentaire pour ce type de réponse comme troisième paramètre facultatif

[SwaggerResponse(200, typeof(CustomModel), "returns a new id of the bla bla")]

Remarque: l'attribut est dans l'espace de noms Swashbuckle.AspNetCore.Annotations

4
L. Mihai