Swashbuckle Parameterbeschreibungen

Question

Ich benutze SwaggerResponse-Attribute, um meine API-Controller-Aktionen zu dekorieren, das alles funktioniert gut, aber wenn ich mir die generierte Dokumentation ansehe, ist das Beschreibungsfeld für Parameter leer.

Gibt es einen attributbasierten Ansatz zur Beschreibung von Aktionsparametern (anstelle von XML-Kommentaren)?

Answer 1

Mit dem neuesten Swashbuckle, oder besser gesagt zumindest die Swashbuckle.AspNetCore variant die ich benutze, das Beschreibung Feld für die Parameter kann nun korrekt als Ausgabe angezeigt werden.

Es erfordert die folgenden Bedingungen erfüllt sein:

• XML comments muss mit Swagger
• Parameter sollten explizit eingerichtet werden, um entweder [FromRoute], [FromQuery], [FromBody] oder aktiviert und konfiguriert werden [FromUri]
• Gleiches gilt für die Methode Typen (Get/Post/put etc.), die mit [Http...] dekoriert werden soll
• die Parameter wie gewohnt mit einem <param ...> xml Kommentar Beschreiben

Eine vollständige Probe sieht wie folgt aus:

/// <summary> 
/// Short, descriptive title of the operation 
/// </summary> 
/// <remarks> 
/// More elaborate description 
/// </remarks> 
/// <param name="id">Here is the description for ID.</param> 
[ProducesResponseType(typeof(Bar), (int)HttpStatusCode.OK)] 
[HttpGet, Route("{id}", Name = "GetFoo")] 
public async Task<IActionResult> Foo([FromRoute] long id) 
{ 
    var response = new Bar(); 
    return Ok(response); 
} 

, die die folgende Ausgabe erzeugt:

Answer 2

Sie sollten bestätigen, dass Sie Prahlerei erlauben XML zu verwenden, kommentiert

httpConfig.EnableSwagger(c => { 
       if (GetXmlCommentsPath() != null) { 
        c.IncludeXmlComments(GetXmlCommentsPath()); 
       } 
... 
... 
); 

protected static string GetXmlCommentsPath() { 
    var path = HostingEnvironment.MapPath("path to your xml doc file"); 
    return path; 
} 

Sie sollten Sie auch XML-Dokument für Ihr gewünschtes Projekt generieren überprüfen. Unter dem gewünschten Projekt Eigenschaften (Alt + Enter auf der Oberseite des Projektes oder Rechtsklick -> Eigenschaften) ->Build- -> Prüfen XML-Dokumentationsdatei

Answer 3

Der Vollständigkeit halber, wenn neueste Version von Swashbuckle.AspNetCore (2.1.0) und Swashbuckle.SwaggerGen/Ui (6.0.0) verwenden, aktivieren Sie Xml Dokumentationsdateigenerierung in der Build Ihres Projekts

Dann folgende zu Ihrer ConfigureServices() Methode:

services.ConfigureSwaggerGen(options => 
{ 
    options.SingleApiVersion(new Info 
    { 
     Version = "v1", 
     Title = "My API", 
     Description = "API Description" 
    }); 
    options.DescribeAllEnumsAsStrings(); 

    var xmlDocFile = Path.Combine(AppContext.BaseDirectory, $"{_hostingEnv.ApplicationName}.xml"); 
    if (File.Exists(xmlDocFile)) 
    { 
     var comments = new XPathDocument(xmlDocFile); 
     options.OperationFilter<XmlCommentsOperationFilter>(comments); 
     options.ModelFilter<XmlCommentsModelFilter>(comments); 
    } 
});