Настройка раздела "Описание ресурса" страницы справки ASP.NET Web API

Question

Я использую ASP.NET Web API, и он удобно автоматически генерирует документацию для моего API, но некоторые из них не имеют смысла.

Возьмите скриншот ниже в качестве примера.

Это конечная точка GET пользователя по его идентификатору, а в Resource Description раздел показывает таблицу, которая показывает свойства модели пользователя, потому что мое действие контроллера имеет [ResponseType(typeof(User))] аннотаций.

Во-первых, в моем действительном контроллере я убираю Password свойство перед отображением результатов пользователю, чтобы не выставлять конфиденциальную информацию. Таким образом, таблица, приведенная в Resource Description раздел неверен, он говорит, что мой API возвращает поля, которые нет.

Во-вторых, под Additional Information столбец это показывает правила проверки, которые согласуются с User модель. Удобно, но совсем не уместно в этом случае, так как эта конечная точка предназначена для GETПользователь, а не пользователь POSTИнг один.

Итак, мой вопрос, как я могу настроить это Resource Description таблица, чтобы указать, какие поля будут возвращены, и скрыть проверки EF?

В настоящее время я прокомментировал свое действие контроллера следующим образом:

/// <summary>
/// Get a single user identified by ID.
/// </summary>
/// <param name="userId">The ID of the user.</param>
/// <returns>A data collection about the user.</returns>
[ResponseType(typeof(User))]
[Route("api/v1/users/{userId}", Name="GetUser")]
[HttpGet]
public IHttpActionResult GetUser(int userId)
{
    // ...
}

и я настроил страницы справки для чтения документации из файла XML, который создается из этих /// комментарии, когда я строю проект.

Спасибо!

Answer 1

В традиционном приложении MVC модели представлений - это модели, которые возвращаются из вашего контроллера в механизм представлений. В приложении Web API модель представления - это модель, представленная потребителю API.

Как и сейчас, вы используете свою модель данных в качестве модели представления.

Есть много причин отделить модели представления от моделей данных:

1. Безопасность: убедитесь, что конфиденциальные данные (например, пароли) не были случайно представлены
2. Различия в данных между интерфейсом Web API и данными базы данных (например, enum в веб-интерфейсе API против int в базе данных).
3. Помогает обеспечить согласованность веб-интерфейса API даже при изменении внутренних структур данных.
4. Позволяет дифференцировать данные между GET а также POST методы. Например, возможно, определенные данные определяются во время POSTНапример, дата создания записи. Эти данные могут быть возвращены из GET, но вы не хотите, чтобы он был включен в POST,

Вы указали причины № 1 и № 2.

Ваше решение должно быть:

1. Создайте новый класс в качестве модели представления. Прямо сейчас у вас есть User класс модели данных. Создать UserViewModel класс (назовите его как хотите).
2. Добавьте в этот класс членов, которые должны быть доступны пользователю. Не включать Password в твоем случае.
3. Добавьте аннотации, которые будут уместны для просмотра в автоматически сгенерированной справке.
4. Скопируйте данные из User класс к UserViewModel класс и вернуть UserViewModel класс от вашего контроллера.