All documents have been moved to official website of MVC.ApiExplorer. I believe that all you need is there.

 

MVC.ApiExplorer

 

Introduction

Are you a developer who develop RESTFul service with ASP.NET MVC? Have you ever created some new actions and just want a convenient way to make sure that whether your actions are working well or not? The MVC.ApiExplorer is just for you.

MVC.ApiExplorer is a portable, independent component designed to help you explore all actions of controller in an ASP.NET MVC project. It doesn't do the same things like unit test or any QA tools would do. You can still use the unit test tools in the development stage. However, In the case of cooperating with someone else who develop another part of system which will invokes your API, such as frontend JavaScript or flash. MVC.ApiExplorer may be helpful to get your partners to understand your API quickly .

MVC.ApiExplorer automatically generates a test page which will lists all your actions of controller. Then you can do some test directly on the page. It is an easy, efficient way to save your time and life. All you need to do is add a reference of MVC.ApiExplorer to your project and create a page to explore your API.

Requirements

Getting started

It is really simple to install the MVC.ApiExplorer component to your project. Just follow the steps below.

Step1: Add reference of MVC.ApiExplorer.dll in your project.
Step2: Add an action - "ApiTest" for exploring all actions of controller. The action name "ApiTest" can be whatever you want. That just a example in this demo case.
Sept3: Add a view of "ApiTest". In the view, you don't have to do anything but put just one line of code in it to render "Explore" action and specify which controller you want to explore on. The example code is below.

 

@{Html.RenderAction("Explore", "ActionExplore", 
    new { controllerType = typeof(The.controller.you.want.to.explore.HomeController) });}

 


Step4: Add exclusive MapRoute for ApiExplorer. That can avoid some problems which will occurs when ApiExplorer doesn't matches any route in the route table.

 

routes.MapRoute(
    "ApiExplorer",
    "ActionExplore/Explore",
    new { controller = "ActionExplore", action = "Explore" },
    new[]{"MVC.ApiExplorer"}
);

 


All steps are there. To get more understand. Please download the source code and check out how MVC.ApiExplorer works in the demo project. 

How to use it

Run your project and navigate to "ApiTest". You will find that all your actions of HomeController have been displayed on ApiTest page. You can even specify all paraments and invoking method of each action to test it. Once you hit the "Invoke" button. The result of the action will be displayed in result area. That way you can easily see what will a client get when it invoke to your API. 

Advanced

How to avoid redundant actions

If there are some actions you don't want to explore. You can decorate those actions with NonApi attribute then those actions wont be displayed on ApiTest page. For example:

 

[NonApi]
public ActionResult Index()
{
    return View();
}

 

 

Display description of actions

You can also decorate action with Description attribute to give a little information about what your API for. MVC.ApiExplorer will displays the description on the test page.

 

[Description("Get the data from our service. It will requires a key.")]
public ActionResult GetData(string key)
{
    //Do something here...
    return Json(new{Sccess=true, Data = data});
}
 

 

Put the test page in an area

Sometime you want to put the test page in an area. Since RenderAction method will looks for ActionExplorerControler in the area where it belongs to. Certainly, ActionExplorerControler isn't here. That can cause an exception be throw out. So that you have to set the area as empty string to avoid that.

 

@{Html.RenderAction("Explore", "ActionExplore", 
    new { area="", controllerType = typeof(The.controller.belong.to.an.area.Default1Controller) });}

 

 

Display multiple controller in one test page

Don't do that.
MVC.ApiExplorer is not designed to works like that. If you have more then one controller to display. Make new test pages for each of them. There is a simply rule. One controller one test page.



Known issue

When your action returns a result of JSON content. In Firefox browser, it will opens a download window to download the JSON document instead of displaying JSON content in the result area. It is as if you download the file from a website. That is just the way how Firefox treat the JSON content. You can install JSONView extensions to avoid this behavior. 

Feedback

Any suggestion? Please feel free to submit an issue here.

Last edited Nov 8, 2011 at 12:22 AM by millionbonus, version 15