In the previous post, I briefly introduced you to the IApiExplorer which can be used to generate documentation, machine-readable metadata, or a test client. In this blog post, we’re going to take a closer look at the ApiExplorer, which is the default implementation of IApiExplorer, and see how we can use it to generate a simple help page. A help page is nothing more than a web-based documentation for your web APIs. It can contain information like the resource URIs, the allowed HTTP methods and the expected parameters so that other developers who consume your APIs know how to call them. What’s great about this help page is that it will automatically update the content when you modify your APIs.
Now let’s get started by looking at the ApiExplorer.
The main goal of this class is to produce a collection of ApiDescription. It does so by statically inspecting the routes and the available actions inside your controllers. Each ApiDescription describes an API that is available on your service. As you can see from the simplified class diagram below, the ApiDescription contains basic information such as the HttpMethod, the RelativePath, the Documentation, etc. But it also points to an ActionDescriptor which is part of the core Web API component that knows everything about an action. You can use it to access a lot more information such as the action name, the return type, the custom attributes, etc. Similarly, you can access the ParameterDescriptor for the expected parameters.
Now, let’s see how we can use it to generate a help page.
Generating the help page
For the sake of simplicity, I’m going to assume your service is web-hosted side-by-side with MVC much like our default template. See “Other implementations” section below for ideas on how to generate a help page on self-hosted services.
Now, I’ll use the default “Web API” template as the starting point for the code sample.
By default the template project comes with a MVC HomeController and a Web API ValuesController. Let’s modify the Index action of the HomeController to display the help page.
Step 1: Getting the ApiExplorer and passing it to the view
Let add the following two lines to the Index action in the HomeController.
Step 2: Customizing the view to display the APIs
In the Index.cshtml, we can specify the IApiExplorer as the type of the Model.
Then we can iterate through the Model.ApiDescriptions to display the supported HTTP method, the relative URL, the documentation and the expected parameters.
And of course you can customize the HTML to make it slightly prettier. Here is the complete code snipped for the view.
Update 9/27/12: If you’re using .NET 4.5, you’ll need to add the reference to System.Net.Http in your web.config. Otherwise you might get an error like the following: “CS0012: The type 'System.Net.Http.HttpMethod' is defined in an assembly that is not referenced. You must add a reference to assembly 'System.Net.Http, Version=188.8.131.52, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'”. This is because in 4.5, System.Net.Http.dll is coming from the GAC instead of a NuGet package and Razor doesn’t include the reference automatically like it does when the assembly is coming from a NuGet package.
Now when you run the application, you should see the following help page instead.
If you look closer, the API documentation simply says “Documentation for XYZ” which is not very helpful. Let’s add some real documentation for our APIs.
Step 3: Providing the documentation
When generating the documentation for an API, ApiExplorer asks the IDocumentationProvider to supply the content. IDocumentationProvider is an abstraction that let you define your own source of documentation (e.g. database, custom attributes, files, etc). For instance, you can implement a custom IDocumentationProvider that let you specify the documentation through attributes. Here, I’ll show you something better, I’ve implemented a simple IDocumentationProvider (XmlCommentDocumentationProvider) that will grab the documentation from C# XML Documentation Comments.
First, you’ll need to wire-up the custom IDocumentationProvider. A simple way of doing that is through HttpConfiguration. Notice that XmlCommentDocumentationProvider needs to know the path of your XML documentation file.
You can make sure that the XML documentation file is enabled by going to the project properties.
Update 11/03/12: When deploying the service, make sure you include the XML documentation file as part of the project and set the “Copy to Output Directory” in the file properties to “Copy always” or “Copy if newer”.
After that, make sure your APIs are documented using XML comments.
Finally, run the sample again, and voila, the documentation from your XML comment shows up on your help page.
Hiding a controller/action from ApiExplorer
If for any reason, you don’t want an API to show up on the help page, you can exclude it by using the ApiExplorerSettingsAttribute instead of going through the ApiDescription collection and deleting it.
Similarly you can declare the attribute on a controller and all the actions in that controller will be hidden from ApiExplorer.
What I showed you above is just one way of implementing the help page. There’re other ways you can implement it. Here is another idea:
- Create a custom ApiController, you can call it HelpController. Within the controller, have a GET action that returns the API information (you can choose to have it in different formats, including HTML). Internally, the HelpController can just use ApiExplorer to get all the information it needs. The advantage of this approach is that it would work for both self-hosted and web-hosted services.
Hope this helps,