Блог

Главная - Вопросы по программированию - Включая блок XML-документации в Swagger Swashbuckle C#

Включая блок XML-документации в Swagger Swashbuckle C#

#c# #swagger #swagger-ui #swashbuckle #swashbuckle.aspnetcore

Вопрос:

Если я создам метод следующим образом:

     /// <summary>
    /// Summary here
    /// </summary>
    /// <returns>THIS DOES NOT SHOW ANYWHERE</returns>
    /// <remarks>Remarks here</remarks>
    public async Task<string> MyMethod()
    {
        return "Hello World";
    }

И у меня есть Смельчак.AspNetCore установлен и настроен, затем документация сгенерирована правильно, за исключением того, что значение в <returns> блоке не генерируется ни во что в json:

 "/api/v1.0/Exhibits/TestMethod1": {
      "get": {
        "tags": [
          "Blah"
        ],
        "summary": "Summary here",
        "description": "Remarks here",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string"
                }
              },
              "text/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },

Как я могу убедить его экспортировать это в соответствующее поле, или это невозможно?

Комментарии:

1. Добавление развязности в ASP.NET Основной веб-API с использованием XML-документации

2. @stuartd у автора этой статьи та же проблема: » Если вам интересно, куда делся возвращаемый XML-узел, ну, я тоже не уверен. Я был бы признателен, если бы кто-нибудь мог указать, где это находится в Чванстве в комментариях».

3. О, прости, что пропустил это

Ответ №1:

Документация по ответу (возврат конечной точки) полностью документирована с помощью
описания определения, типа содержимого, схемы и т. Д. для каждого кода состояния

Таким образом, описание возврата отличается, зависит от кода состояния в каждом ответе. поэтому вам нужно указать, что является описанием для каждого кода статуса.

Swagger используйте один или несколько <response code="xxx"> вместо одного <returns>

ваш документ должен выглядеть следующим образом

 /// <summary>
/// Retrieves a specific product by unique id
/// </summary>
/// <remarks>Awesomeness!</remarks>
/// <response code="200">Product created</response>
/// <response code="400">Product has missing/invalid values</response>
/// <response code="500">Oops! Can't create your product right now</response>
[HttpGet("{id}")]
[ProducesResponseType(typeof(Product), 200)]
[ProducesResponseType(typeof(IDictionary<string, string>), 400)]
[ProducesResponseType(500)]
public Product GetById(int id)

подробнее читайте, как добавить описание метода в пользовательский интерфейс Swagger в приложении WebAPI

Метки: