web-dev-qa-db-fra.com

Comment faire pour que Swagger affiche des exemples d'objets renvoyés par l'API?

Je crée un ensemble d'API pour la première fois. Voici l'une des méthodes:

    // GET: api/Doors/0
    /// <summary>
    /// Get a list of all doors for a given organization.
    /// </summary>
    /// <param name="organizationSys">The Organization ID for which all doors should be retreived.</param>
    /// <returns></returns>
    [Route("{organizationSys:int}")]
    public IHttpActionResult Get(int organizationSys)
    {
        try
        {
            Dictionary<string, object> parameters = new Dictionary<string, object>();
            parameters.Add("@OrganizationSys", organizationSys);
            List<Door> doors = Repository<Doors>.GetList("WHERE OrganizationSys = @OrganizationSys", parameters).ToList();
            if (doors == null || doors.Count() == 0)
                return Content(HttpStatusCode.NotFound, RejectionMessage.NoItemsFound);

            return Ok(doors);
        }
        catch (Exception ex)
        {
            return Content(HttpStatusCode.BadRequest, ex.Message);
        }
    }

J'ai mis en place un test unitaire sur ce point final, et cela fonctionne parfaitement. Cependant, j'ai une question.

Dans Swagger, je voudrais montrer un exemple de l'objet de données qui sera retourné. Le seul type de retour sur la méthode est IHttpActionResult donc je ne suis pas surpris qu'il ne montre pas le modèle de données dans Swagger. Alors, que dois-je changer avec cette méthode pour que l'objet de retour (dans ce cas List<Door>) sera plus visible?

Swashbuckle prend-il cela en charge?

Merci!

c#.netapiswaggerswashbuckle
9
Casey Crookston

Cela devrait être assez simple:

[Route("{organizationSys:int}")]
[ProducesResponseType(typeof(List<Door>), 200)]
[ProducesResponseType(typeof(string), 400)]
public IHttpActionResult Get(int organizationSys)

Notez que puisque vous avez 2 points de sortie: un retour normal avec des données et un catch avec ce qui renvoie un message d'erreur, j'ai défini dans l'exemple ci-dessus deux types de résultats possibles:

  • http: 200 (OK) avec List<Door>
  • http: 400 (BadRequest) avec string

L'infrastructure Swashbuckle Swagger lira cela et fournira des exemples très approximatifs des données pour ces cas.

Cependant, si vous avez besoin d'exemples plus détaillés (c'est-à-dire avec des valeurs de champ raisonnables), vous devrez implémenter "fournisseur d'exemples". Voir ici pour les détails et le tutoriel rapide , en bref:

[SwaggerRequestExample(typeof(DeliveryOptionsSearchModel), typeof(DeliveryOptionsSearchModelExample))]
public async Task<IHttpActionResult> DeliveryOptionsForAddress(DeliveryOptionsSearchModel search)

et

public class DeliveryOptionsSearchModelExample : IExamplesProvider
{
  public object GetExamples()
  {
    return new DeliveryOptionsSearchModel
    {
        Lang = "en-GB",
        Currency = "GBP",
        Address = new AddressModel
        {
            Address1 = "1 Gwalior Road",
            Locality = "London",
            Country = "GB",
            PostalCode = "SW15 1NP"
        },
        Items = new[]
        {
            new ItemModel
            {
                ItemId = "ABCD",
                ItemType = ItemType.Product,
                Price = 20,
                Quantity = 1,
                RestrictedCountries = new[] { "US" }
            }
        }
    };
}

L'exemple de fournisseur fonctionne de manière très simple: quoi que le fournisseur renvoie, il est sérialisé en JSON et renvoyé comme exemple pour le type de données donné . Juste comme ça.

Maintenant, si votre méthode renvoyait DeliveryOptionsSearchModel, le fournisseur utiliserait directement ces données ci-dessus.

Ou, si votre méthode a renvoyé un objet plus grand, composé de DeliveryOptionsSearchModel et de quelques autres, Swagger utiliserait ce fournisseur pour une partie de l'exemple de réponse et un autre fournisseur (ou des exemples approximatifs par défaut) pour toutes les autres parties de le grand objet.

Tout ce qui précède était pour Net Core.

Si vous utilisez Net 4.5/4.6/4.7 "normal", cette méthode n'est pas disponible, car la classe Attribute n'existe pas. Dans AspMvc pour Net 4.x, il n'y a qu'un attribut [ResponseType(typeof(..))] qui permet de définir un seul type de retour. C'est OK pour la plupart du temps. Cependant, si vous avez vraiment besoin de différencier les types de retour par rapport aux codes de réponse, ou si vous devez fournir de bons exemples, c'est un problème.

Pourtant! Quelques bonnes personnes ont déjà résolu cela. Voir cet article . Il décrit NuGet Swagger.Examples, Je crois que c'est pour les non-core, et il vise à fournir de meilleures descriptions de résultats.

Il définit un autre attribut - [SwaggerResponse(HttpStatusCode.OK, Type=typeof(IEnumerable... Pour définir les codes de résultat et les types de résultats possibles et fournit un plugin pour que Swagger utilise cet attribut.

Il fournit également un autre attribut, [SwaggerResponseExample... Qui permet de définir le fournisseur d'exemple de résultat, qui peut fournir un bon exemple personnalisé avec des données, tout comme IExampleProvider décrit ci-dessus pour Core. Soigné!

15
quetzalcoatl