C# Web API Help Documentation IHttpActionResult

asp.net-web-api2crest

I have a C# Web API and I am trying to get the auto created help documentation to work with IHttpActionResult. I stripped down the example below so its a little easier to read.

For the object, below is a simple example. BusinessObject is just a wrapper. The CollectionBase is CollectionBase : ObservableCollection<T>, ILoadable where T : BusinessObject. Its an older code base that is auto generated but reusing it for this.

    public class Value : BusinessObject
    {
        public int Id { get; set; }
    }
    public class Values : CollectionBase<Value>
    {
        public override Value LoadObject(System.Data.IDataRecord record)
        {
            return new Value();
        }
    }

For the API side of things. The following works.

public class Values : ApiController
{
    public IEnumerable<Value> GetThis()
    {
        Values values = new Values();
        return values;
    }
}

enter image description here

The issue comes when I try to do

    public IHttpActionResult GetThis()
    {
        Values values = new Values();
        return Ok(values);
    }

It doesn't recognize that it should use a different return type. The 'Resource Description' ends up being IHttpActionResult with no sample output. Now I can add

config.SetActualResponseType(typeof(IEnumerable<Value>), "Values", "GetThis");

and it will show a sample output but the 'Resource Description' will still be IHttpActionResult. That is the main issue I am having. I would like to use IHttpActionResult because its very easy to use and can return error codes if needed very easily. I would just like to be able to auto construct the documentation.

UPDATE: Upon some further research, I did fine this post.
Resource Description on Web API Help page is showing "None."

Bascially, you add the response type attribute to the method.

[ResponseType(typeof(IEnumerable<Value>))]
public IHttpActionResult GetThis()
{
    Values values = new Values();
    return Ok(values);
}

Although this technically works and I have modified my existing code to use this. It would still be nice if there was a way to have it automatically figure it out somehow. Not sure if this is possible or not.

Best Answer

This works for what I am doing. Its a little tedious to have to include every time but it allows me to return error codes if necessary and retain the help documentation functionality.

[ResponseType(typeof(IEnumerable<Value>))]
public IHttpActionResult GetThis()
{
    Values values = new Values();
    return Ok(values);
}

Resource Description on Web API Help page is showing "None."

Method A: HttpClient (Preferred)

Available in: .NET Framework 4.5+, .NET Standard 1.1+, .NET Core 1.0+ .

It is currently the preferred approach, and is asynchronous and high performance. Use the built-in version in most cases, but for very old platforms there is a NuGet package.

using System.Net.Http;

Setup

It is recommended to instantiate one HttpClient for your application's lifetime and share it unless you have a specific reason not to.

private static readonly HttpClient client = new HttpClient();

See HttpClientFactory for a dependency injection solution.

POST

var values = new Dictionary<string, string>
{
    { "thing1", "hello" },
    { "thing2", "world" }
};

var content = new FormUrlEncodedContent(values);

var response = await client.PostAsync("http://www.example.com/recepticle.aspx", content);

var responseString = await response.Content.ReadAsStringAsync();

GET

var responseString = await client.GetStringAsync("http://www.example.com/recepticle.aspx");

Method B: Third-Party Libraries

RestSharp

POST

 var client = new RestClient("http://example.com");
 // client.Authenticator = new HttpBasicAuthenticator(username, password);
 var request = new RestRequest("resource/{id}");
 request.AddParameter("thing1", "Hello");
 request.AddParameter("thing2", "world");
 request.AddHeader("header", "value");
 request.AddFile("file", path);
 var response = client.Post(request);
 var content = response.Content; // Raw content as string
 var response2 = client.Post<Person>(request);
 var name = response2.Data.Name;

Flurl.Http

It is a newer library sporting a fluent API, testing helpers, uses HttpClient under the hood, and is portable. It is available via NuGet.

    using Flurl.Http;

POST

var responseString = await "http://www.example.com/recepticle.aspx"
    .PostUrlEncodedAsync(new { thing1 = "hello", thing2 = "world" })
    .ReceiveString();

GET

var responseString = await "http://www.example.com/recepticle.aspx"
    .GetStringAsync();

Method C: HttpWebRequest (not recommended for new work)

Available in: .NET Framework 1.1+, .NET Standard 2.0+, .NET Core 1.0+. In .NET Core, it is mostly for compatibility -- it wraps HttpClient, is less performant, and won't get new features.

using System.Net;
using System.Text;  // For class Encoding
using System.IO;    // For StreamReader

POST

var request = (HttpWebRequest)WebRequest.Create("http://www.example.com/recepticle.aspx");

var postData = "thing1=" + Uri.EscapeDataString("hello");
    postData += "&thing2=" + Uri.EscapeDataString("world");
var data = Encoding.ASCII.GetBytes(postData);

request.Method = "POST";
request.ContentType = "application/x-www-form-urlencoded";
request.ContentLength = data.Length;

using (var stream = request.GetRequestStream())
{
    stream.Write(data, 0, data.Length);
}

var response = (HttpWebResponse)request.GetResponse();

var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();

GET

var request = (HttpWebRequest)WebRequest.Create("http://www.example.com/recepticle.aspx");

var response = (HttpWebResponse)request.GetResponse();

var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();

Method D: WebClient (Not recommended for new work)

This is a wrapper around HttpWebRequest. Compare with HttpClient.

Available in: .NET Framework 1.1+, NET Standard 2.0+, .NET Core 2.0+

using System.Net;
using System.Collections.Specialized;

POST

using (var client = new WebClient())
{
    var values = new NameValueCollection();
    values["thing1"] = "hello";
    values["thing2"] = "world";

    var response = client.UploadValues("http://www.example.com/recepticle.aspx", values);

    var responseString = Encoding.Default.GetString(response);
}

GET

using (var client = new WebClient())
{
    var responseString = client.DownloadString("http://www.example.com/recepticle.aspx");
}

C# – Pass an array of integers to ASP.NET Web API

You just need to add [FromUri] before parameter, looks like:

GetCategories([FromUri] int[] categoryIds)

And send request:

/Categories?categoryids=1&categoryids=2&categoryids=3

Best Answer

Related Solutions

C# – How to make an HTTP POST web request

Method A: HttpClient (Preferred)

Setup

Method B: Third-Party Libraries

Method C: HttpWebRequest (not recommended for new work)

Method D: WebClient (Not recommended for new work)

C# – Pass an array of integers to ASP.NET Web API

Related Topic