New: Add documentation for blobAPI(coscine/issues#1108)

src/Blob/Blob.csproj

@@ -33,6 +33,7 @@
     <DefineConstants>DEBUG;TRACE</DefineConstants>
     <ErrorReport>prompt</ErrorReport>
     <WarningLevel>4</WarningLevel>
+    <DocumentationFile>bin\Debug\Coscine.Api.Blob.xml</DocumentationFile>
   </PropertyGroup>
   <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
     <PlatformTarget>AnyCPU</PlatformTarget>
@@ -42,6 +43,7 @@
     <DefineConstants>TRACE</DefineConstants>
     <ErrorReport>prompt</ErrorReport>
     <WarningLevel>4</WarningLevel>
+    <DocumentationFile>bin\Debug\Coscine.Api.Blob.xml</DocumentationFile>
   </PropertyGroup>
   <ItemGroup>
     <Reference Include="AWSSDK.Core, Version=3.3.0.0, Culture=neutral, PublicKeyToken=885c28607f98e604, processorArchitecture=MSIL">

src/Blob/Controllers/BlobController.cs

@@ -22,7 +22,11 @@ using System.Web;
 
 namespace Coscine.Api.Blob.Controllers
 {
+    /// <summary>
+    /// This controller represents the actions which can be taken with a Blob object.
+    /// </summary>
     [Authorize]
+    
     public class BlobController : Controller
     {
         private readonly IConfiguration _configuration;
@@ -39,6 +43,13 @@ namespace Coscine.Api.Blob.Controllers
         private readonly string _rdsResourceHost;
         private readonly WaterbutlerInterface _waterbutlerInterface;
 
+
+        
+        /// <summary>
+        /// Blob controller constructor
+        /// </summary>
+        /// <param name="logger">Logger</param>
+        /// <param name="dataSourceService">Source service for data</param>
         public BlobController(ILogger<BlobController> logger, IDataSourceService dataSourceService)
         {
             _configuration = Program.Configuration;
@@ -61,7 +72,11 @@ namespace Coscine.Api.Blob.Controllers
             _dataSourceService = dataSourceService;
             _waterbutlerInterface = new WaterbutlerInterface(_configuration, _dataSourceService);
         }
-
+        /// <summary>
+        /// This method returns the amount of allocated space for the given resource
+        /// </summary>
+        /// <param name="resourceId">Id of a resource</param>
+        /// <returns>Data, file count and bytesize used </returns>
         [HttpGet("[controller]/{resourceId}/quota")]
         public IActionResult GetQuota(string resourceId)
         {
@@ -140,6 +155,13 @@ namespace Coscine.Api.Blob.Controllers
         // inferring a ../ (urlencoded) can manipulate the url.
         // However the constructed signature for s3 won't match and it will not be resolved.
         // This may be a problem for other provider!
+
+        /// <summary>
+        ///  This method checks if the given file exists
+        /// </summary>
+        /// <param name="resourceId">Id of the resource</param>
+        /// <param name="path"> Path to the file </param>
+        /// <returns>Ok if file exists otherwise error </returns>
         [HttpGet("[controller]/{resourceId}/{*path}")]
         [DisableRequestSizeLimit]
         public async Task<IActionResult> GetFile(string resourceId, string path)
@@ -205,6 +227,13 @@ namespace Coscine.Api.Blob.Controllers
         // inferring a ../ (urlencoded) can manipulate the url.
         // However the constructed signature for s3 won't match and it will not be resolved.
         // This may be a problem for other provider!
+
+        /// <summary>
+        /// This method uploads a given File
+        /// </summary>
+        /// <param name="resourceId">Id of the resource </param>
+        /// <param name="path">Path to the file</param>
+        /// <returns>Ok if file is uploaded otherwise error</returns>
         [HttpPut("[controller]/{resourceId}/{*path}")]
         [DisableRequestSizeLimit]
         public async Task<IActionResult> UploadFile(string resourceId, string path)
@@ -284,7 +313,12 @@ namespace Coscine.Api.Blob.Controllers
 
             }
         }
-
+        /// <summary>
+        /// This method deletes a given file
+        /// </summary>
+        /// <param name="resourceId">Id of the resource </param>
+        /// <param name="path">Path to the file</param>
+        /// <returns>Ok if deletion successful otherwise returns error </returns>
         [HttpDelete("[controller]/{resourceId}/{*path}")]
         public async Task<IActionResult> DeleteFile(string resourceId, string path)
         {
@@ -345,14 +379,15 @@ namespace Coscine.Api.Blob.Controllers
                 }
             }
         }
-
+        /// <summary>
+        /// This method checks if the resource is valid
+        /// </summary>
+        /// <returns>Ok if resource is valid otherwise returns error</returns>
         [HttpPost("[controller]/validate")]
-        public async Task<IActionResult> IsResourceValid()
+        public async Task<IActionResult> IsResourceValid([FromBody] JToken resource)
         {
             var path = "/";
 
-            JToken resource = ObjectFactory<JToken>.DeserializeFromStream(Request.Body);
-
             string authHeader = null;
             if (resource["type"]["displayName"].ToString().ToLower() == "s3")
             {
@@ -394,6 +429,9 @@ namespace Coscine.Api.Blob.Controllers
                 return NoContent();
             }
         }
+        /// <summary>
+        /// Returns the name of the resource
+        /// </summary>
 
         private string GetResourceTypeName(Resource resource)
         {
@@ -406,6 +444,9 @@ namespace Coscine.Api.Blob.Controllers
                 return resource.Type.DisplayName.ToLower();
             }
         }
+        /// <summary>
+        /// Returns the name of the resource
+        /// </summary>
 
         private string GetResourceTypeName(JToken resource)
         {
@@ -418,6 +459,9 @@ namespace Coscine.Api.Blob.Controllers
                 return resource["type"]["displayName"].ToString().ToLower();
             }
         }
+        /// <summary>
+        /// Creates an Action Result that can be returned on error
+        /// </summary>
 
         private IActionResult FailedRequest(HttpResponseMessage response, string path)
         {
@@ -434,7 +478,9 @@ namespace Coscine.Api.Blob.Controllers
                 return BadRequest($"Error in communication with waterbutler: {response.StatusCode}");
             }
         }
-
+        /// <summary>
+        /// Tries to establish connection with resource and validates wether the given file/folder exists
+        /// </summary>
         private IActionResult CheckResourceIdAndPath(string resourceId, string path, out Resource resource)
         {
             resource = null;
@@ -479,6 +525,11 @@ namespace Coscine.Api.Blob.Controllers
         }
 
         // XXX extract in the future to an analytics Controller
+
+        /// <summary>
+        /// Writes an analytics log entry
+        /// </summary>
+
         private void LogAnalytics(string operation, string resourceId, string path, User user)
         {
             if (CoscineLoggerConfiguration.IsLogLevelActivated(LogType.Analytics))

src/Blob/Program.cs

@@ -3,8 +3,14 @@ using Coscine.Configuration;
 
 namespace Coscine.Api.Blob
 {
+    /// <summary>
+    /// Standard Program Class
+    /// </summary>
     public class Program : AbstractProgram<ConsulConfiguration>
     {
+        /// <summary>
+        /// Standard main body
+        /// </summary>
         public static void Main()
         {
             System.Net.ServicePointManager.DefaultConnectionLimit = int.MaxValue;

src/Blob/Startup.cs

@@ -5,12 +5,21 @@ using System;
 
 namespace Coscine.Api.Blob
 {
+    /// <summary>
+    /// Standard Startup class.
+    /// </summary>
     public class Startup : AbstractStartup
     {
+        /// <summary>
+        /// Standard Startup constructor.
+        /// </summary>
         public Startup()
         {
         }
-
+        /// <summary>
+        /// Configures custom service extenions
+        /// </summary>
+        /// <param name="services">services</param>
         public override void ConfigureServicesExtension(IServiceCollection services)
         {
             base.ConfigureServicesExtension(services);