Clever Geek Handbook

Configuring the Resource Description Section on the ASP.NET Web API Help Page

I am using ASP.NET Web API and it automatically generates documentation for my API, but some of them don't make sense.

Take the screenshot below as an example.

Screenshot

This is the endpoint for the GET

user by their id, and the section Resource Description

shows a table that shows the properties of the user model since my controller action is annotated [ResponseType(typeof(User))]

.

First, in my actual controller action, I remove the property Password

before displaying the results to the user so as not to expose sensitive information. Therefore, the table given in the section Resource Description

is not correct, as my API returns fields that are not there.

Second, in a column, Additional Information

it shows the validation rules that come with the model User

. Convenient, but not entirely appropriate in this case, as this endpoint is for the GET

user and not POST

for input.

So my question is, how do I set up this table Resource Description

to specify which fields will be returned and hide EF checks?

Currently I have commented out my controller action like this:

/// <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)
{
    // ...
}

and I configured the help pages to read the documentation from the XML file that is generated from these comments ///

when the project is created.

Thank!

+3


source to share


1 answer


In a traditional MVC application, viewmodels are the models that are returned from your controller to the viewer. In a Web API application, the view model is the model presented to the API consumer.

As of now, you are using a data model as your view model.

There are many reasons to decouple view models from data models:

  • Security: Make sure that sensitive data (such as passwords) is not accidentally displayed.
  • Differences in data between web API and database data (for example, enum

    in the web API and int

    in the database).
  • Helps to ensure that the web API remains consistent even if internal data structures change.
  • Allows you to distinguish data between methods GET

    and POST

    . For example, perhaps certain data is determined at the time of POST

    ing, such as the creation date of the record. This data can be returned from GET

    , but you do not want it to be included in POST

    .


You are faced with reasons # 1 and # 2.

Your solution should be:

  • Create a new class as a model for your view. You now have a data model class User

    . Create a class UserViewModel

    (name it whatever you want).
  • Add members to this class that should be available to the user. Don't include Password

    in your case.
  • Add annotations that would be appropriate for the auto-generated help.
  • Copy data from class User

    to class UserViewModel

    and return the class UserViewModel

    from your controller.
+1


source






More articles:


All Articles