Asp.Net Core Swagger / FromForm /// (тройной слэш) комментарии не подобраны? - PullRequest
Новая
       10

Asp.Net Core Swagger / FromForm /// (тройной слэш) комментарии не подобраны?

0 голосов
/ 08 января 2019

У меня есть метод контроллера, который выглядит следующим образом: 

[HttpPost]
[Consumes("application/x-www-form-urlencoded")]
[Produces("application/json")]
public async Task<IActionResult> GenerateTokenAsync([FromForm]TokenParameters tokenParameters)

TokenParameters выглядит так: 

public class TokenParameters
{
    /// <summary>
    /// Specifies the grant type. Must be "password".
    /// </summary>
    [Required]
    public GrantType? grant_type
    {
        get;
        set;
    }

    /// <summary>
    /// Specifies the username.
    /// </summary>
    [Required]
    public string username
    {
        get;
        set;
    }

    /// <summary>
    /// Specifies the password.
    /// </summary>
    [Required]
    public string password
    {
        get;
        set;
    }
}

Все работает нормально, но пользовательский интерфейс Swagger не собирает комментарии /// тройного слеша для участников. Мои другие контроллеры используют FromBody и /// комментарии с тройной косой чертой прекрасно с ними работают. Похоже, что раздел модели внизу собирает комментарии, но я говорю об описании модели в светло-зеленом разделе, когда смотрю на контроллер.

Я посмотрел в реестре схемы, и описания действительно есть.

РЕДАКТИРОВАТЬ: Использование Swashbuckle 5.0 Beta.

РЕДАКТИРОВАТЬ # 2: Кажется, он также не берет значения примера из реестра схемы для параметров формы.

Есть идеи?

Ответы [ 2 ]

0 голосов
/ 09 апреля 2019

У меня тоже была эта проблема. Моя проблема заключалась в том, что я не включал правильные XML-файлы документации. Я включал только веб-приложение документацию XML, в то время как у меня был мой объект "параметров создания", который создавался из данных формы, определенных в другой сборке. Когда у меня была эта сборка, производящая документацию XML и включающая ее в конфигурацию сваггера, я смогла получить описания для каждого элемента поля формы.

Вот мой метод контроллера, обрабатывающий POST от клиента: 

/// <summary>
/// Create a new very complex object.
/// </summary>
/// <param name="creationOptions">Very complex creation options</param>
/// <returns>The very complex object as a data transfer object.</returns>
[HttpPost]
[Consumes("application/x-www-form-urlencoded")]
public async Task<IActionResult> CreateVeryComplexObject([FromForm] VeryComplexObjectCreationOptions creationOptions) { }

При добавлении сервисов swagger я включил документацию из обеих сборок: 

services.AddSwaggerGen(config =>
{
    // All my other swagger configuration here...

    config.IncludeXmlComments(System.IO.Path.Combine(AppContext.BaseDirectory, "MyService.API.Web.xml"));
    config.IncludeXmlComments(System.IO.Path.Combine(AppContext.BaseDirectory, "MyService.API.Contracts.xml"));
});

Это на Swashbuckle 4.0.1.

0 голосов
/ 08 января 2019

Убедитесь, что в вашем проекте отмечена опция Generate xml documentation.

Кроме того, когда вы настраиваете Swagger, убедитесь, что он включает комментарии xml. 

// Register the Swagger generator, defining one or more Swagger documents
services.AddSwaggerGen(c =>
{
  c.SwaggerDoc("v2", new Info { Title = "my API", Version = "v2" });

  // Set the comments path for the Swagger JSON and UI.
  var basePath = PlatformServices.Default.Application.ApplicationBasePath;
  var xmlPath = Path.Combine(basePath, "myapp.xml");
  c.IncludeXmlComments(xmlPath);
});
...