Nel precedente script abbiamo avuto modo di vedere come, con la recente ASP.NET and Web Tools 2012.2, il template di progetto ASP.NET Web API si sia arricchito di una serie di pagine di help che descrivono i vari metodi esposti dalle nostre API, recuperando eventualmente le varie descrizioni dalla documentazione XML che abbiamo inserito nel codice.

Queste pagine, oltre al testo descrittivo, mostrano anche alcuni esempi di request e response per tutti i media type supportati, che, per default, vengono prodotti a partire da dati autogenerati e poco significativi.

Un'ulteriore problema è costituito dal fatto che l'engine sfrutta i MediaTypeFormatter registrati nel sistema per produrre le varie serializzazioni e, nel caso in cui questa operazione non sia supportata, viene generato un messaggio di errore; è il caso di FormUrlEncodedMediaTypeFormatter, che produce questo testo per application/x-www-form-urlencoded:

Per risolvere questo tipo di problemi e rendere più efficaci e esplicative queste pagine, nella solita classe HelpPageConfig possiamo impostare per ogni coppia tipo/media type il testo desiderato:

string personJsonSample = @"{
  ""Id"": 1,
  ""Name"": ""Marco"",
  ""BirthDate"": ""1977-07-10"",
  ""City"": ""Milano""
}";

config.SetSampleForType(personJsonSample, 
  MediaTypeHeaderValue.Parse("application/json"), typeof(Person));
config.SetSampleForType(personJsonSample, 
  MediaTypeHeaderValue.Parse("text/json"), typeof(Person));

string personFormSample = "Id=1&Name=\"Marco\"&City=\"Milano\"";
config.SetSampleForType(personFormSample, 
  MediaTypeHeaderValue.Parse("application/x-www-form-urlencoded"), typeof(Person));

Nell'esempio precedente, abbiamo associato alla serializzazione JSON e a una richiesta proveniente da una form HTML un esempio molto più significativo per la classe Person. Il risultato è quello visibile in figura:

Un altro aspetto su cui l'engine ha difficoltà a intervenire è quello di metodi che restituiscono un generico HttpResponseMessage, come il seguente:

public HttpResponseMessage Get(int id)
{
  Person result = // ... ricerca su database ...;

  if (person != null)
    this.Request.CreateResponse(HttpStatusCode.OK, new Person());
  else
    this.Request.CreateErrorResponse(HttpStatusCode.NotFound, "Entity not found");
}

In questi casi, infatti, l'engine non può avere cognizione del tipo effettivamente restituito e, pertanto, non è in grado di generare alcun esempio. Per ovviare al problema possiamo sfruttare il metodo SetActualResponseType per indicare che, al di là della signature del metodo, la action Get restituirà in realtà un oggetto di tipo Person:

config.SetActualResponseType(typeof(Person), "PeopleServices", "Get", "id");