EC-000 Swagger and redoc

Comments/Comments.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
+<Project Sdk="Microsoft.NET.Sdk.Web">
 
   <PropertyGroup>
     <TargetFramework>netcoreapp2.1</TargetFramework>
@@ -8,6 +8,8 @@
     <SpaRoot>ClientApp\</SpaRoot>
     <DefaultItemExcludes>$(DefaultItemExcludes);$(SpaRoot)node_modules\**</DefaultItemExcludes>
     <UserSecretsId>69e0e9e3-debe-4946-a1fe-f8956079c9fa</UserSecretsId>
+	<GenerateDocumentationFile>true</GenerateDocumentationFile>
+	<NoWarn>$(NoWarn);1591</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>
@@ -29,6 +31,7 @@
     <PackageReference Include="NICE.Auth.NetCore" Version="1.0.106" />
     <PackageReference Include="NICE.Feeds" Version="1.0.136" />
     <PackageReference Include="NICE.Logging" Version="5.0.52" />
+    <PackageReference Include="NSwag.AspNetCore" Version="12.0.13" />
     <PackageReference Include="Serilog.Sinks.RollingFile" Version="3.3.0" />
   </ItemGroup>
 

Comments/Controllers/Api/AnswerController.cs

@@ -1,4 +1,6 @@
 using Comments.Services;
+using Comments.ViewModels;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
 
@@ -16,9 +18,15 @@ public AnswerController(IAnswerService answerService, ILogger<AnswerController>
             _logger = logger;
         }
 
-        // GET: consultations/api/Answer/5 
-        [HttpGet("{answerId}")]
-        public IActionResult GetAnswer([FromRoute] int answerId)
+		// GET: consultations/api/Answer/5
+		/// <summary>
+		/// Get single answer from id
+		/// </summary>
+		/// <param name="answerId">id of the answer</param>
+		/// <returns>Returns the answer view model</returns>
+		[HttpGet("{answerId}")]
+        [ProducesResponseType(typeof(Answer), StatusCodes.Status200OK)]
+		public IActionResult GetAnswer([FromRoute] int answerId)
         {
             if (!ModelState.IsValid)
             {
@@ -36,9 +44,15 @@ public IActionResult GetAnswer([FromRoute] int answerId)
             return invalidResult ?? Ok(result.answer);
         }
 
-        // POST: consultations/api/Answer
-        [HttpPost]
-        public IActionResult PostAnswer([FromBody] ViewModels.Answer answer) 
+		// POST: consultations/api/Answer
+		/// <summary>
+		/// Adds a single answer
+		/// </summary>
+		/// <param name="answer">answer view model</param>
+		/// <returns>Returns the answer view model and Validate model</returns>
+		[HttpPost]
+		[ProducesResponseType(typeof((Answer, Validate)), StatusCodes.Status200OK)]
+		public IActionResult PostAnswer([FromBody] ViewModels.Answer answer) 
         {
             if (!ModelState.IsValid)
             {
@@ -52,9 +66,16 @@ public IActionResult PostAnswer([FromBody] ViewModels.Answer answer)
             return invalidResult ?? CreatedAtAction("GetAnswer", new { id = result.answer.AnswerId }, result.answer);
         }
 
-        // PUT: consultations/api/Answer/5
-        [HttpPut("{answerId}")]
-        public IActionResult PutAnswer([FromRoute] int answerId, [FromBody] ViewModels.Answer answer)
+		// PUT: consultations/api/Answer/5
+		/// <summary>
+		/// Updates an individual answer based on answer Id
+		/// </summary>
+		/// <param name="answerId">ID of the answer to be updated</param>
+		/// <param name="answer">The values the answer is to be updated with</param>
+		/// <returns>Returns the answer view model of the updated answer</returns>
+		[HttpPut("{answerId}")]
+		[ProducesResponseType(typeof(Answer), StatusCodes.Status200OK)]
+		public IActionResult PutAnswer([FromRoute] int answerId, [FromBody] ViewModels.Answer answer)
         {
             if (!ModelState.IsValid)
             {
@@ -72,9 +93,15 @@ public IActionResult PutAnswer([FromRoute] int answerId, [FromBody] ViewModels.A
             return invalidResult ?? Ok(answer);
         }
 
-        // DELETE: consultations/api/Answer/5
-        [HttpDelete("{answerId}")]
-        public IActionResult DeleteAnswer([FromRoute] int answerId)
+		// DELETE: consultations/api/Answer/5
+		/// <summary>
+		/// Deletes an individual answer specified by answer Id
+		/// </summary>
+		/// <param name="answerId">Id of the answer to be deleted</param>
+		/// <returns>Returns the number of rows affected</returns>
+		[HttpDelete("{answerId}")]
+		[ProducesResponseType(typeof((int, Validate)), StatusCodes.Status200OK)]
+		public IActionResult DeleteAnswer([FromRoute] int answerId)
         {
             if (!ModelState.IsValid)
             {

Comments/Controllers/Api/ChapterController.cs

@@ -4,6 +4,7 @@
 using Microsoft.Extensions.Logging;
 using System;
 using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Http;
 
 namespace Comments.Controllers.Api
 {
@@ -18,17 +19,19 @@ public ChapterController(IConsultationService consultationService, ILogger<Chapt
         {
             _consultationService = consultationService;
             _logger = logger;
-        }
+		}
 
+		// GET: eg. consultations/api/Chapter?consultationId=1&documentId=2&chapterSlug=introduction
 		/// <summary>
-		/// GET: eg. consultations/api/Chapter?consultationId=1&documentId=2&chapterSlug=introduction
+		/// Returns chapter content for a document
 		/// </summary>
 		/// <param name="consultationId">int</param>
 		/// <param name="documentId">int</param>
 		/// <param name="chapterSlug">non-empty string</param>
 		/// <returns></returns>
 		[HttpGet]
-        public ChapterContent Get(int consultationId, int documentId, string chapterSlug)
+		[ProducesResponseType(typeof(ChapterContent), StatusCodes.Status200OK)]
+		public ChapterContent Get(int consultationId, int documentId, string chapterSlug)
         {
             if (string.IsNullOrWhiteSpace(chapterSlug))
                 throw new ArgumentNullException(nameof(chapterSlug));
@@ -51,15 +54,17 @@ public PreviewChapterController(IConsultationService consultationService, ILogge
 			_logger = logger;
 		}
 
+		// GET: eg. consultations/api/PreviewChapter?consultationId=1&documentId=2&chapterSlug=introduction&reference=GID-TA10232
 		/// <summary>
-		/// GET: eg. consultations/api/PreviewChapter?consultationId=1&documentId=2&chapterSlug=introduction&reference=GID-TA10232
+		/// Returns Chapter content for a document in preview mode
 		/// </summary>
 		/// <param name="consultationId">int</param>
 		/// <param name="documentId">int</param>
 		/// <param name="chapterSlug">non-empty string</param>
 		/// <param name="reference">non-empty string</param>
 		/// <returns></returns>
 		[HttpGet]
+		[ProducesResponseType(typeof(ChapterContent), StatusCodes.Status200OK)]
 		public ChapterContent Get(int consultationId, int documentId, string chapterSlug, string reference)
 		{
 			if (string.IsNullOrWhiteSpace(chapterSlug))

Comments/Controllers/Api/CommentController.cs

@@ -1,6 +1,7 @@
-using Comments.Services;
+using Comments.Services;
 using Comments.ViewModels;
 using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
 
@@ -20,9 +21,15 @@ public CommentController(ICommentService commentService, ILogger<CommentsControl
             _logger = logger;
         }
 
-        // GET: consultations/api/Comment/5 
-        [HttpGet("{commentId}")]
-        public IActionResult GetComment([FromRoute] int commentId)
+		// GET: consultations/api/Comment/5
+		/// <summary>
+		/// Get single comment from id
+		/// </summary>
+		/// <param name="commentId">id of the comment</param>
+		/// <returns>Return the comment view model</returns>
+		[HttpGet("{commentId}")]
+        [ProducesResponseType(typeof((Comment, Validate)), StatusCodes.Status200OK)]
+		public IActionResult GetComment([FromRoute] int commentId)
         {
             if (!ModelState.IsValid)
             {
@@ -35,9 +42,16 @@ public IActionResult GetComment([FromRoute] int commentId)
             return invalidResult ?? Ok(result.comment);
         }
 
-        // PUT: consultations/api/Comment/5
-        [HttpPut("{commentId}")]
-        public IActionResult PutComment([FromRoute] int commentId, [FromBody] ViewModels.Comment comment)
+		// PUT: consultations/api/Comment/5
+		/// <summary>
+		/// Updates an comment based on comment Id
+		/// </summary>
+		/// <param name="commentId">Id of the comment</param>
+		/// <param name="comment">The values the comment is to be updated with</param>
+		/// <returns>Return the comment view model</returns>
+		[HttpPut("{commentId}")]
+        [ProducesResponseType(typeof(Comment), StatusCodes.Status200OK)]
+		public IActionResult PutComment([FromRoute] int commentId, [FromBody] ViewModels.Comment comment)
         {
             if (!ModelState.IsValid)
             {
@@ -55,9 +69,15 @@ public IActionResult PutComment([FromRoute] int commentId, [FromBody] ViewModels
             return invalidResult ?? Ok(comment);
         }
 
-        // POST: consultations/api/Comment
-        [HttpPost]
-        public IActionResult PostComment([FromBody] ViewModels.Comment comment)
+		// POST: consultations/api/Comment
+		/// <summary>
+		/// Adds a single comment
+		/// </summary>
+		/// <param name="comment">comment view model</param>
+		/// <returns>Returns the comment view model and Validate model</returns>
+		[HttpPost]
+        [ProducesResponseType(typeof((Comment,Validate)), StatusCodes.Status200OK)]
+		public IActionResult PostComment([FromBody] ViewModels.Comment comment)
         {
             if (!ModelState.IsValid)
             {
@@ -70,9 +90,15 @@ public IActionResult PostComment([FromBody] ViewModels.Comment comment)
             return invalidResult ?? CreatedAtAction("GetComment", new { id = result.comment.CommentId }, result.comment);
         }
 
-        // DELETE: consultations/api/Comment/5
-        [HttpDelete("{commentId}")]
-        public IActionResult DeleteComment([FromRoute] int commentId)
+		// DELETE: consultations/api/Comment/5
+		/// <summary>
+		/// Deletes an individual comment specified by comment Id
+		/// </summary>
+		/// <param name="commentId">Id of the comment to be deleted</param>
+		/// <returns>Returns the number of rows affected</returns>
+		[HttpDelete("{commentId}")]
+        [ProducesResponseType(typeof((int, Validate)), StatusCodes.Status200OK)]
+		public IActionResult DeleteComment([FromRoute] int commentId)
         {
             if (!ModelState.IsValid)
             {
@@ -85,4 +111,4 @@ public IActionResult DeleteComment([FromRoute] int commentId)
             return invalidResult ?? Ok(result.rowsUpdated);
         }
     }
-}
+}

Comments/Controllers/Api/CommentsController.cs

@@ -5,6 +5,7 @@
 using Microsoft.Extensions.Logging;
 using System;
 using System.Collections.Generic;
+using Microsoft.AspNetCore.Http;
 
 namespace Comments.Controllers.Api
 {
@@ -18,32 +19,36 @@ public CommentsController(ICommentService commentService, ILogger<CommentsContro
         {
             _commentService = commentService;
             _logger = logger;
-        }
+		}
 
+		// GET: eg. consultations/api/Comments?sourceURI=%2Fconsultations%2F1%2F1%2Fchapter-slug
 		/// <summary>
-		/// GET: eg. consultations/api/Comments?sourceURI=%2Fconsultations%2F1%2F1%2Fchapter-slug
+		/// Returns a list of comments for a given URI, restricted by current user
 		/// </summary>
 		/// <param name="sourceURI">this is really the relativeURL eg "/1/1/introduction" on document page</param>
-		/// <returns></returns>
+		/// <returns>CommentsAndQuestions</returns>
 		[Route("consultations/api/[controller]")]
 		[HttpGet]
-        public CommentsAndQuestions Get(string sourceURI)
+		[ProducesResponseType(typeof(CommentsAndQuestions), StatusCodes.Status200OK)]
+		public CommentsAndQuestions Get(string sourceURI)
         {
             if (string.IsNullOrWhiteSpace(sourceURI))
                 throw new ArgumentNullException(nameof(sourceURI));
 
             return _commentService.GetCommentsAndQuestions(relativeURL: sourceURI);
-        }
+		}
 
+		// GET: eg. consultations/api/CommentsForReview?relativeURL=%2F1%2Freview
 		/// <summary>
-		/// GET: eg. consultations/api/CommentsForReview?relativeURL=%2F1%2Freview
+		/// Returns a list of comments for a given URI, restricted by current user. For the review page.
 		/// </summary>
 		/// <param name="relativeURL">this is the relativeURL eg "/1/review" on review page</param>
 		/// <param name="reviewPageViewModel"></param>
-		/// <returns></returns>
+		/// <returns>ReviewPageViewModel</returns>
 		[Route("consultations/api/[controller]ForReview")]
 	    [HttpGet]
-	    public ReviewPageViewModel Get(string relativeURL, ReviewPageViewModel reviewPageViewModel)
+		[ProducesResponseType(typeof(ReviewPageViewModel), StatusCodes.Status200OK)]
+		public ReviewPageViewModel Get(string relativeURL, ReviewPageViewModel reviewPageViewModel)
 	    {
 			if (string.IsNullOrWhiteSpace(relativeURL))
 				throw new ArgumentNullException(nameof(relativeURL));

Comments/Controllers/Api/ConsultationController.cs

@@ -5,6 +5,7 @@
 using System;
 using System.Collections.Generic;
 using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Http;
 
 namespace Comments.Controllers.Api
 {
@@ -19,14 +20,15 @@ public ConsultationController(IConsultationService consultationService, ILogger<
         {
             _consultationService = consultationService;
             _logger = logger;
-        }
+		}
 
+        // GET: eg. consultations/api/Consultation?consultationId=1
 		/// <summary>
-		/// GET: eg. consultations/api/Consultation?consultationId=1
+		/// Returns details of a single consultation
 		/// </summary>
-		/// <param name="consultationId"></param>
-		/// <param name="isReview">boolean indicating if the feed isbeing accessed for reviewing purposes</param>
-		/// <returns></returns>
+		/// <param name="consultationId"> Id of the consultation</param>
+		/// <param name="isReview">Boolean indicating if the feed isbeing accessed for reviewing purposes</param>
+		/// <returns>Consultation ViewModel</returns>
 		[HttpGet]
         public ViewModels.Consultation Get(int consultationId, bool isReview = false)
         {
@@ -51,15 +53,17 @@ public DraftConsultationController(IConsultationService consultationService, ILo
 			_logger = logger;
 		}
 
+		// GET: eg. consultations/api/DraftConsultation?consultationId=1&documentId=1&reference=GID-TA1232
 		/// <summary>
-		/// GET: eg. consultations/api/DraftConsultation?consultationId=1&documentId=1&reference=GID-TA1232
+		/// Returns details for a single consultation that has never been published.
 		/// </summary>
-		/// <param name="consultationId"></param>
-		/// <param name="documentId"></param>
-		/// <param name="reference"></param>
-		/// <param name="isReview">boolean indicating if the feed isbeing accessed for reviewing purposes</param>
-		/// <returns></returns>
+		/// <param name="consultationId">Id of the consultation</param>
+		/// <param name="documentId"> Id of the document</param>
+		/// <param name="reference">Reference Id of the consultation e.g. GID-TA1232</param>
+		/// <param name="isReview">Boolean indicating if the feed is being accessed for reviewing purposes</param>
+		/// <returns>Consultation ViewModel</returns>
 		[HttpGet]
+		[ProducesResponseType(typeof(Consultation), StatusCodes.Status200OK)]
 		public ViewModels.Consultation Get(int consultationId, int documentId, string reference, bool isReview = false)
 		{
 			if (consultationId < 1)

Comments/Controllers/Api/ConsultationListController.cs

@@ -1,5 +1,7 @@
+using System.Collections.Generic;
 using Comments.Services;
 using Comments.ViewModels;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
 
@@ -17,15 +19,18 @@ public ConsultationListController(IConsultationListService consultationListServi
         {
 	        _consultationListService = consultationListService;
             _logger = logger;
-        }
+		}
 
+	    // GET: eg. consultations/api/ConsultationList?Status=Open&Status=Closed
+	    // Note: the repeated querystring parameter. this is how default model binding to an array works. don't pass a CSV list and expect it to work without writing something custom (like I did)
 		/// <summary>
-		/// GET: eg. consultations/api/ConsultationList?Status=Open&Status=Closed
-		/// note: the repeated querystring parameter. this is how default model binding to an array works. don't pass a CSV list and expect it to work without writing something custom (like I did)
+		/// Returns a list of consultations for the download page.
 		/// </summary>
-		/// <returns></returns>
+		/// <param name="consultationListViewModel"></param>
+		/// <returns>ConsultationListViewModel, Valdate</returns>
 		[HttpGet]
-        public IActionResult Get(ConsultationListViewModel consultationListViewModel)
+		[ProducesResponseType(typeof((ConsultationListViewModel consultationListViewModel, Validate validate)), StatusCodes.Status200OK)]
+		public IActionResult Get(ConsultationListViewModel consultationListViewModel)
 		{
 			var result = _consultationListService.GetConsultationListViewModel(consultationListViewModel);