Working With API Help Page Controller In Web API

In this article we are going to see how we can enable the API descriptions for a better understanding of how our API controller works and what exactly it is supposed to do. It is recommended to give the summary and parameter lists and a bit of an introduction to the service whenever you write any API services. Here I am going to use create a Web API in Visual Studio 2015. I hope you will like this.

You can always download the source code here: API Help Page Documentation

Create table with data

Our database is ready, now create a Web API application in visual studio and then entity with the above mentioned database.

1. public class ProductsController : ApiController
2. {
3. private TrialsDBEntities db = new TrialsDBEntities();
4. // GET: api/Products
5. public IQueryable<Product> GetProducts()
6. {
7. return db.Products;
8. }
9. // GET: api/Products/5
10. [ResponseType(typeof(Product))]
11. public IHttpActionResult GetProduct(int id)
12. {
13. Product product = db.Products.Find(id);
14. if (product == null)
15. {
16. return NotFound();
17. }
18. return Ok(product);
19. }
20. // PUT: api/Products/5
21. [ResponseType(typeof(void))]
22. public IHttpActionResult PutProduct(int id, Product product)
23. {
24. if (!ModelState.IsValid)
25. {
26. return BadRequest(ModelState);
27. }
28. if (id != product.ProductID)
29. {
30. return BadRequest();
31. }
32. db.Entry(product).State = EntityState.Modified;
33. try
34. {
35. db.SaveChanges();
36. }
37. catch (DbUpdateConcurrencyException)
38. {
39. if (!ProductExists(id))
40. {
41. return NotFound();
42. }
43. else
44. {
45. throw;
46. }
47. }
48. return StatusCode(HttpStatusCode.NoContent);
49. }
50. // POST: api/Products
51. [ResponseType(typeof(Product))]
52. public IHttpActionResult PostProduct(Product product)
53. {
54. if (!ModelState.IsValid)
55. {
56. return BadRequest(ModelState);
57. }
58. db.Products.Add(product);
59. try
60. {
61. db.SaveChanges();
62. }
63. catch (DbUpdateException)
64. {
65. if (ProductExists(product.ProductID))
66. {
67. return Conflict();
68. }
69. else
70. {
71. throw;
72. }
73. }
74. return CreatedAtRoute("DefaultApi", new
75. {
76. id = product.ProductID
77. }, product);
78. }
79. // DELETE: api/Products/5
80. [ResponseType(typeof(Product))]
81. public IHttpActionResult DeleteProduct(int id)
82. {
83. Product product = db.Products.Find(id);
84. if (product == null)
85. {
86. return NotFound();
87. }
88. db.Products.Remove(product);
89. db.SaveChanges();
90. return Ok(product);
91. }
92. protected override void Dispose(bool disposing)
93. {
94. if (disposing)
95. {
96. db.Dispose();
97. }
98. base.Dispose(disposing);
99. }
100. private bool ProductExists(int id)
101. {
102. return db.Products.Count(e => e.ProductID == id) > 0;
103. }
104. }
     

Now please run your application and go to the help page. You can see the API help page as follows.


API Help Page

As you can see ‘No documentation available.’ under description of all the service actions. No worries we will try to add some summary to the actions now. So we will change the code as follows.

• Go to Areas\HelpPage\App_Start and click on the file HelpPageConfig.cs.
• Uncomment the following line from the static function Register.
  
  1. config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("App_Data/XmlDocument.xml")));
     
  
  
• Right click on your project and go to properties, then click on Build
• Go to Output section and click on XML documentation file and then type~/App_Data/XmlDocument.xml in the given text box.
• Save and build your project.

This will create a XML document with the name XmlDocument.xml in App_Data folder. Once it is generated, the summary you have described in your API controller will be listed there. Initially the file will be in excluded state, you may need to include the same to your project when you deploy your API application. For that please follows the below steps.

API Help Page With Descriptions

Have a happy coding!.

Conclusion

Did I miss anything that you may think is needed? Did you find this post useful? I hope you liked this article. Please share with me your valuable suggestions and feedback.

Your turn. What do you think?

A blog isn’t a blog without comments, but do try to stay on topic. If you have a question unrelated to this post, you’re better off posting it on C# Corner, Code Project, Stack Overflow, Asp.Net Forum instead of commenting here. Tweet or email me a link to your question there and I’ll definitely try to help if I can.