Populating description fields in Webapi help pages

Bsrkvarma
Posted by in ASP.NET Web API category on for Intermediate level | Points: 250 | Views : 476 red flag

Populating the description fields in WEBAPI help pages is pretty simple most of the times, if the model/contract projects are located in the same WEBAPI project. But we face issues, when the models are located in different projects. I have discussed about one of the work around for such problem in this post..

Introduction

we were given a task, in which the dynamically generated WEBAPI help pages has to show the description of the web methods and the properties.

Thanks to the great post Implementing Web-API help Page which helped us in figuring out the steps need to be followed for generating the WebAPI help pages dynamically..

But the same didn’t worked in our case.

           

Code snippets

The difference between my application and the sample project in the post is the models are located in different project rather than in same project.

We did some work around to address the problem.

We configured the XML documentation file for the both project as below 


XML documentation path for Webapi project.


XML documentation path for Contracts project.


And modified the Register method in the HelpPageConfig.cs file to combine both the XML summary comments files and set the WEBAPI to use the updated XML summary comments file.

public static void Register(HttpConfiguration config)

{

XmlDocument apiDoc = new XmlDocument();

apiDoc.Load(HttpContext.Current.Server.MapPath("~/App_Data/WebApi.Orders.xml"));

XmlDocument contractsDoc = new XmlDocument();

contractsDoc.Load(HttpContext.Current.Server.MapPath("~/App_Data/Contracts.xml"));

if (contractsDoc.DocumentElement != null && apiDoc.DocumentElement!=null)

{

       XmlNodeList nodes = contractsDoc.DocumentElement.ChildNodes;

       foreach (XmlNode node in nodes)

       {

              XmlNode copiedNode = apiDoc.ImportNode(node, true);

              apiDoc.DocumentElement.AppendChild(copiedNode);

       }

apiDoc.Save(HttpContext.Current.Server.MapPath("~/App_Data/WebApi.Orders.xml"));

}

config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/ WebApi.Orders.xml")));

}

The above code will combine both the XML summary comments files and generates the single XML summary comments file and we used the same to configure the WEBAPI XmlDocumentationProvider in the configuration.

           

Conclusion

In scenarios where the contract/Models are located in different project other than the WEBAPI project, then we can use this kind f workarounds like combining  the XML summary comments files generated in different projects to a single XML summary comment file and then provide it to  the config.SetDocumentationProvider() method to generate the description fields.

Reference

http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages

Page copy protected against web site content infringement by Copyscape

About the Author

Bsrkvarma
Full Name: varma bsrk
Member Level: Starter
Member Status: Member
Member Since: 8/25/2014 9:07:08 AM
Country: India
Varma
http://www.dotnetfunda.com
I have 4.5 + years of experience in .Net application development.

Login to vote for this post.

Comments or Responses

Login to post response

Comment using Facebook(Author doesn't get notification)