From 2406ec0e3e76f9063e93814289cf7a3440b1a1c3 Mon Sep 17 00:00:00 2001
From: Hamid Reza Mohammadi <mohammadi.hr@gmail.com>
Date: Fri, 13 May 2022 12:03:14 +0430
Subject: [PATCH] docs: #319 API for retrieving a poem section information

---
 RMuseum/Controllers/GanjoorController.cs      | 22 +++++++++++++++++++
 RMuseum/RMuseum.xml                           | 21 ++++++++++++++++++
 RMuseum/Services/IGanjoorService.cs           |  7 ++++++
 .../GanjoorService-PoemSections.cs            | 13 +++++++++++
 4 files changed, 63 insertions(+)

diff --git a/RMuseum/Controllers/GanjoorController.cs b/RMuseum/Controllers/GanjoorController.cs
index 0527c9fb..f5a91579 100644
--- a/RMuseum/Controllers/GanjoorController.cs
+++ b/RMuseum/Controllers/GanjoorController.cs
@@ -2795,6 +2795,28 @@ namespace RMuseum.Controllers
             return Ok(res.Result);
         }
 
+        /// <summary>
+        /// get a specific poem section
+        /// </summary>
+        /// <param name="sectionId"></param>
+        /// <returns></returns>
+        [HttpGet]
+        [Route("section/{sectionId}")]
+        [AllowAnonymous]
+        [ProducesResponseType((int)HttpStatusCode.OK, Type = typeof(IEnumerable<GanjoorPoemSection>))]
+        [ProducesResponseType((int)HttpStatusCode.BadRequest, Type = typeof(string))]
+        [ProducesResponseType((int)HttpStatusCode.NotFound)]
+        public async Task<IActionResult> GetPoemSectionByIdAsync(int sectionId)
+        {
+            var res =
+                await _ganjoorService.GetPoemSectionByIdAsync(sectionId);
+            if (!string.IsNullOrEmpty(res.ExceptionString))
+                return BadRequest(res.ExceptionString);
+            if (res.Result == null)
+                return NotFound();
+            return Ok(res.Result);
+        }
+
         /// <summary>
         /// start band couplets fix
         /// </summary>
diff --git a/RMuseum/RMuseum.xml b/RMuseum/RMuseum.xml
index e023c783..b64efb39 100644
--- a/RMuseum/RMuseum.xml
+++ b/RMuseum/RMuseum.xml
@@ -1707,6 +1707,13 @@
             <param name="poemId"></param>
             <returns></returns>
         </member>
+        <member name="M:RMuseum.Controllers.GanjoorController.GetPoemSectionByIdAsync(System.Int32)">
+            <summary>
+            get a specific poem section
+            </summary>
+            <param name="sectionId"></param>
+            <returns></returns>
+        </member>
         <member name="M:RMuseum.Controllers.GanjoorController.StartOnTimeBandCoupletsFix">
             <summary>
             start band couplets fix
@@ -12367,6 +12374,13 @@
             <param name="id"></param>
             <returns></returns>
         </member>
+        <member name="M:RMuseum.Services.IGanjoorService.GetPoemSectionByIdAsync(System.Int32)">
+            <summary>
+            get a specific poem section
+            </summary>
+            <param name="sectionId"></param>
+            <returns></returns>
+        </member>
         <member name="M:RMuseum.Services.IGanjoorService.GetLastUnreviewedUserCorrectionForSection(System.Guid,System.Int32)">
             <summary>
             last unreviewed user correction for a section
@@ -14096,6 +14110,13 @@
             <param name="id"></param>
             <returns></returns>
         </member>
+        <member name="M:RMuseum.Services.Implementation.GanjoorService.GetPoemSectionByIdAsync(System.Int32)">
+            <summary>
+            get a specific poem sections
+            </summary>
+            <param name="sectionId"></param>
+            <returns></returns>
+        </member>
         <member name="M:RMuseum.Services.Implementation.GanjoorService.StartOnTimeBandCoupletsFix">
             <summary>
             start band couplets fix
diff --git a/RMuseum/Services/IGanjoorService.cs b/RMuseum/Services/IGanjoorService.cs
index f8e1dd06..b9fb95b9 100644
--- a/RMuseum/Services/IGanjoorService.cs
+++ b/RMuseum/Services/IGanjoorService.cs
@@ -942,6 +942,13 @@ namespace RMuseum.Services
         /// <returns></returns>
         Task<RServiceResult<GanjoorPoemSection[]>> GetPoemSectionsAsync(int id);
 
+        /// <summary>
+        /// get a specific poem section
+        /// </summary>
+        /// <param name="sectionId"></param>
+        /// <returns></returns>
+        Task<RServiceResult<GanjoorPoemSection>> GetPoemSectionByIdAsync(int sectionId);
+
         /// <summary>
         /// last unreviewed user correction for a section
         /// </summary>
diff --git a/RMuseum/Services/Implementation/GanjoorService-Partials/GanjoorService-PoemSections.cs b/RMuseum/Services/Implementation/GanjoorService-Partials/GanjoorService-PoemSections.cs
index 174ebb76..5b516502 100644
--- a/RMuseum/Services/Implementation/GanjoorService-Partials/GanjoorService-PoemSections.cs
+++ b/RMuseum/Services/Implementation/GanjoorService-Partials/GanjoorService-PoemSections.cs
@@ -642,6 +642,19 @@ namespace RMuseum.Services.Implementation
             return new RServiceResult<GanjoorPoemSection[]>(sections);
         }
 
+        /// <summary>
+        /// get a specific poem sections
+        /// </summary>
+        /// <param name="sectionId"></param>
+        /// <returns></returns>
+        public async Task<RServiceResult<GanjoorPoemSection>> GetPoemSectionByIdAsync(int sectionId)
+        {
+            return new RServiceResult<GanjoorPoemSection>
+                (
+                await _context.GanjoorPoemSections.AsNoTracking().Include(s => s.GanjoorMetre).Where(s => s.Id == sectionId).SingleOrDefaultAsync()
+                );
+        }
+
         /// <summary>
         /// start band couplets fix
         /// </summary>