Thursday, April 18, 2013

Razor brush for Alex Gorbatchev's SyntaxHighlighter

While I was putting together a new blog post about customizing the Web API Help page I took a look at how to display code in Blogger. SyntaxHighlighter is a popular tool for highlighting code in your blog posts which uses Javascript files and CSS to modify code snippets.

I followed this quick guide to using SyntaxHighlighter with Blogger (tip: don't add script references to brushes that you're not using!) and was generally pleased with the results but sad that no Razor brush is available. After a quick dabble however I have created a quick and dirty Razor brush for SyntaxHighlighter which I hope people find useful!

Example razor syntax:

Monday, April 8, 2013

Customize the ASP.NET Web API Help page with REST style groupings

If (like me) you are keeping up to speed with Microsoft's ASP.NET Web API framework you might have noticed the recent release of the ASP.NET and Web Tools 2012.2 Update. What was exciting for me in this release was the addition of an automatically generated help page which can be configured to use comments in your code for the documentation. What better way to maintain the documentation for a web service than in the code itself?

Although the display of the default help page is pretty comprehensive from the start, I wanted to change the way it grouped items to better suit my implementation of a REST service. 

During the creation of my Web API project I had considered using a separate Controller for each unique request with the 4 standard HTTP methods available (GET, POST, PUT & DELETE). In practice however it seemed neater to consider a Controller as a business entity (e.g. Customer) and to allow for several Actions types within it. This cuts down on the number of separate .cs files needed in the project and provides a logical grouping for developers trying to navigate your API e.g. 
  • Customer/Address
  • Customer/Invoices
  • etc.
In order to update the help page to group by entity/controller and then list action names and available methods I made the following changes;
  1. Areas\HelpPage\Views\Help\Index.cshtml
  2. Areas\HelpPage\Views\Help\DisplayTemplates\ApiGroup.cshtml
  3. Areas\HelpPage\HelpPage.css
1) Update the Index to include Action in the object model and then render a separate table for each Controller. The way the table is implemented in code here is pretty ugly in IMHO but I'm new to the Razor syntax and it works, so...

2) Update the rendering of the Action names to group by HTTP method and only list the action name once per url. Also add an HTTP link back to the service to allow immediate testing of GET's;

3) Beautify the CSS(!)

And that's all there is to it, a self-documenting REST style Web API service which can be maintained by developers, for developers - pretty neat!