Add comments to API methods for Swagger

Author: rxtur

src/Core/Api/AuthorsController.cs

@@ -30,6 +30,11 @@ public AuthorsController(IDataService data, IStorageService store, UserManager<A
             _store = store;
         }
 
+        /// <summary>
+        /// Get list of blog authors
+        /// </summary>
+        /// <param name="page">Page number</param>
+        /// <returns>List of authors</returns>
         [HttpGet]
         public async Task<ActionResult<IEnumerable<Author>>> Get(int page = 1)
         {
@@ -45,6 +50,11 @@ public async Task<ActionResult<IEnumerable<Author>>> Get(int page = 1)
             }
         }
 
+        /// <summary>
+        /// Get single author by name
+        /// </summary>
+        /// <param name="author">Author name used during registration</param>
+        /// <returns>Author object</returns>
         [HttpGet("{author}")]
         public async Task<ActionResult<Author>> Get(string author)
         {
@@ -61,6 +71,11 @@ public async Task<ActionResult<Author>> Get(string author)
             }
         }
 
+        /// <summary>
+        /// Register new author. Authorized admins only.
+        /// </summary>
+        /// <param name="model">Author model</param>
+        /// <returns>Created Author object</returns>
         [HttpPost]
         [Administrator]
         public async Task<ActionResult<Author>> Post(RegisterModel model)
@@ -98,6 +113,11 @@ public async Task<ActionResult<Author>> Post(RegisterModel model)
             }
         }
 
+        /// <summary>
+        /// Update author
+        /// </summary>
+        /// <param name="model">Author model</param>
+        /// <returns>Success or 500 error</returns>
         [HttpPut("update")]
         [Administrator]
         public async Task<ActionResult> Update(Author model)
@@ -117,6 +137,11 @@ public async Task<ActionResult> Update(Author model)
             }
         }
 
+        /// <summary>
+        /// Change author password. Authorized users only.
+        /// </summary>
+        /// <param name="model">Author model</param>
+        /// <returns>Success or 500 error</returns>
         [HttpPut("changepwd")]
         [Authorize]
         public async Task<ActionResult> ChangePwd(ChangePasswordModel model)
@@ -143,6 +168,11 @@ public async Task<ActionResult> ChangePwd(ChangePasswordModel model)
             }
         }
 
+        /// <summary>
+        /// Delete author, from membership, database and file system. Admin only.
+        /// </summary>
+        /// <param name="id">Author ID</param>
+        /// <returns>Success or 500 error</returns>
         [Administrator]
         [HttpDelete("remove/{id}")]
         public async Task<IActionResult> Delete(string id)

src/Core/Api/PostsController.cs

@@ -21,6 +21,13 @@ public PostsController(IDataService data)
             _data = data;
         }
 
+        /// <summary>
+        /// Get list of blog posts
+        /// </summary>
+        /// <param name="term">Search term</param>
+        /// <param name="status">Status; P - published, D - drafts</param>
+        /// <param name="page">Page number</param>
+        /// <returns>Model with list of posts and pager</returns>
         [HttpGet]
         public async Task<ActionResult<PageListModel>> Get([FromQuery]string term = "", [FromQuery]string status = "", [FromQuery]int page = 1)
         {
@@ -66,6 +73,11 @@ await _data.BlogPosts.Search(pager, term) :
             }
         }
 
+        /// <summary>
+        /// Get single post by ID
+        /// </summary>
+        /// <param name="id">Post ID</param>
+        /// <returns>Post item</returns>
         [HttpGet("{id}")]
         public async Task<PostItem> GetPost(int id)
         {
@@ -81,6 +93,12 @@ public async Task<PostItem> GetPost(int id)
             }               
         }
 
+        /// <summary>
+        /// Set post as published or draft
+        /// </summary>
+        /// <param name="id">Post ID</param>
+        /// <param name="flag">Flag; P - publish, U - unpublish</param>
+        /// <returns>Success of failure</returns>
         [HttpPut("publish")]
         [Authorize]
         public async Task<ActionResult> Publish(int id, string flag)
@@ -106,6 +124,12 @@ public async Task<ActionResult> Publish(int id, string flag)
             }
         }
 
+        /// <summary>
+        /// Set post as featured
+        /// </summary>
+        /// <param name="id">Post ID</param>
+        /// <param name="flag">Flag; F - featured, U - remove from featured</param>
+        /// <returns></returns>
         [HttpPut("feature")]
         [Administrator]
         public async Task<ActionResult> Feature(int id, string flag)
@@ -131,6 +155,11 @@ public async Task<ActionResult> Feature(int id, string flag)
             }
         }
 
+        /// <summary>
+        /// Save blog post
+        /// </summary>
+        /// <param name="post">Post item</param>
+        /// <returns>Saved post item</returns>
         [HttpPost]
         [Authorize]
         public async Task<ActionResult<PostItem>> Post(PostItem post)
@@ -147,6 +176,11 @@ public async Task<ActionResult<PostItem>> Post(PostItem post)
             }
         }
 
+        /// <summary>
+        /// Remove post item
+        /// </summary>
+        /// <param name="id">Post ID</param>
+        /// <returns>Success or failure</returns>
         [HttpDelete("remove/{id}")]
         [Authorize]
         public async Task<IActionResult> Remove(int id)

src/Core/Api/SettingsController.cs

@@ -27,6 +27,10 @@ public SettingsController(IDataService data, IOptions<RequestLocalizationOptions
             _options = options;
         }
 
+        /// <summary>
+        /// Get list of cultures
+        /// </summary>
+        /// <returns>List of supported languages</returns>
         [HttpGet("cultures")]
         public async Task<ActionResult<List<SelectListItem>>> GetCultures()
         {
@@ -44,6 +48,10 @@ public async Task<ActionResult<List<SelectListItem>>> GetCultures()
             }
         }
 
+        /// <summary>
+        /// Get blog settings
+        /// </summary>
+        /// <returns>Blog settings</returns>
         [HttpGet]
         [Administrator]
         public async Task<ActionResult<BlogItem>> Get()
@@ -59,6 +67,11 @@ public async Task<ActionResult<BlogItem>> Get()
             }
         }
 
+        /// <summary>
+        /// Save blog settings
+        /// </summary>
+        /// <param name="model">Blog settings item</param>
+        /// <returns>Saved blog item</returns>
         [HttpPost]
         [Administrator]
         public async Task<ActionResult<BlogItem>> Post(BlogItem model)

src/Core/Api/ThemesController.cs

@@ -26,6 +26,11 @@ public ThemesController(IDataService data, IStorageService store)
             _store = store;
         }
 
+        /// <summary>
+        /// Get list of themes
+        /// </summary>
+        /// <param name="page">Page number</param>
+        /// <returns>List of themes</returns>
         [HttpGet]
         public async Task<ActionResult<IEnumerable<ThemeItem>>> Get(int page = 1)
         {
@@ -42,6 +47,11 @@ public async Task<ActionResult<IEnumerable<ThemeItem>>> Get(int page = 1)
             }
         }
 
+        /// <summary>
+        /// Set theme as current for a blog
+        /// </summary>
+        /// <param name="id">Theme ID</param>
+        /// <returns>Success or failure</returns>
         [Administrator]
         [HttpPut("select/{id}")]
         public ActionResult Put(string id)
@@ -68,6 +78,11 @@ public ActionResult Put(string id)
             }
         }
 
+        /// <summary>
+        /// Remove and unistall theme from the blog
+        /// </summary>
+        /// <param name="id">Theme ID</param>
+        /// <returns>Success or failure</returns>
         [Administrator]
         [HttpDelete("remove/{id}")]
         public IActionResult Delete(string id)