DPS907 notes – Thu Oct 6

Documentation, embedded in a web service. Hands-on with Assignment 5.


Documentation for your web service

As you would expect, there are different kinds of documentation in a web service:

  1. Code comments
  2. Out-of-band (web page) documentation for users/requestors
  3. Embedded documentation in responses (representations)


Code comments are for the programmer (duh). You should add code comments to introduce a section of code that needs it, and to explain logic that is not apparent or is dependent on context or disjointed knowledge.

Out-of-band documentation is for users/requestors. It is typically presented on a set of web pages. The ASP.NET Web API project type has a very nice documentation generator. If you do your part (explained below), it will automatically generate these web pages. Sweet.

Embedded documentation is found in the responses delivered to users/requestors. You have recently learned about link relations, which provide some documentation. Today (below), you will learn a few more ways to improve this situation.


Code comments, and
Out-of-band (web page) documentation

When you run your app, it loads in a browser. You may have noticed an “API” link on the top-of-page menu strip.



The link will show you pages that are generated by the Web API Help Page feature. This feature is turned on in every new Web API project in Visual Studio 2015. (Its principal author is again, Yao Huang Lin. A busy guy.)

Its default configuration will show a list of all the requests that can be handled by your app’s controllers. It does this by looking for classes that inherit from ApiController, and then inspecting their methods and routes. The ApiExplorer class enables this feature.

In its default configuration, every documented request has a “Description” field that reads “No documentation available”. We should change that, to make the documentation more useful:



Implementing the Web API Help Page

There are several discrete tasks to fully implement a useful Web API Help Page.

Change the project’s properties

Open the project properties panel, and show the Build settings.

In the “Errors and warnings” settings, add “CS1591” to the “Suppress warnings” textbox. As it suggests, it will suppress warnings for C# compiler warning number 1591.

In the “Output” settings, check (mark) the “XML documentation file” setting, and add a file path name (App_Data\XmlDocument.xml) to the textbox. As it suggests, the compiler will output/save the data to that named file.

Save, and close the project properties panel.



Configure the help page to use the just-configured XML documentation file

Open the source code file that holds the HelpPageConfig class. It’s in Areas > HelpPage > App_Start.

Uncomment the statement that sets/configures the XML documentation file:



Add documentation to controller methods

For each public web service controller method, add XML Documentation Comments.

If you have never used this feature, here’s how to get started: Position the cursor on the line above the method declaration statement. Type a triple slash ( / / / ). That will add the structure. Then, fill it in with useful comments.

Incidentally, you can add XML Documentation Comments to every method and property, in every class, in your project. Then, during coding, Visual Studio will use the data as you write code, and show it with its code sense feature. (Yes, this is how Microsoft has done this for framework-provided code.)



When you build and run your project, the compiler will generate the content it needs to fully configure the Web API Help Page feature.

Please follow the instructions above. They are intended for late 2015 projects. However, you should also read/skim the original documents that describe the Web API Help Page feature, because they include some background information and so on. Be careful, because some of the documents are two or three years old, and may not (or will not) apply to current new projects.

Creating Help Pages for ASP.NET Web API, by Mike Wasson, April 2013

Introducing the ASP.NET Web API Help Page, by Yao Huang Lin, August 2012

More info, Part 1, Part 2, and Part 3, by Yao, also from 2012


Configure an initial URI for the web service

docs-initial-uriA hypermedia-driven design also needs an “initial URI“.

The idea is that the web service provider can publish one single URI for the web service, and clients/requestors will be able to use that to discover all of the available resources.

To do this, we must perform these steps:

  1. Add a default value “Root” for the “controller” placeholder, in the App_Start > WebApiConfig class
  2. Add a new ApiController class (named “RootController”) that uses the value you provided above
  3. Implement a single “get” method, which returns a collection of link relations

The LinkRelationsMore code example was enhanced with this feature.


Deliver a template for an “add new” request

Here’s a scenario: A user of your web service wants to add a new Vehicle object. What properties must be provided? Which data types are used? Are there any other constraints?

One popular solution is to deliver a template with the response to the “get-all” request. That’s the most natural place for it, because we’re already delivering a link relation for the collection.

How do we implement this? We complete two simple tasks:

  1. Add a resource model class for the template
  2. Add a property to the “get-all” link relations container class for a template object


Add a resource model class…

Add a resource model class for the template, named <Entity>AddTemplate.

It has string properties. The property names match – exactly – the names of the properties in the <Entity>Add resource model class.

All properties have getters only. No setters. When initialized, the class object has all it needs to tell a story to the user.

The value of each string property will tell the user about the data they must send, including data types and other constraints (length, range, etc.).


Add a property…

Add a property to the “get-all” link relations container class (the pluralized “linked” class). Add code in the constructor to initialize the property’s value.


Get started on the assignment

Assignment 5 is now available.

Before leaving the classroom at the end of the timeslot, hand in your work report.



























%d bloggers like this: