Merge branch 'Topic/1114-docuTreeApi' into 'Product/938-docuTreeApi'

New: Add documentation for treeAPI(coscine/issues#1114)

See merge request coscine/api/treeapi!7

src/Tree/Controllers/TreeController.cs

@@ -24,6 +24,9 @@ using VDS.RDF.Writing;
 
 namespace Coscine.Api.Tree.Controllers
 {
+    /// <summary>
+    /// This controller represents the actions which can be taken with a tree object.
+    /// </summary>
     [Authorize]
     public class TreeController : Controller
     {
@@ -39,6 +42,11 @@ namespace Coscine.Api.Tree.Controllers
         private readonly string _blobApiLink;
         private readonly string _prefix;
 
+        /// <summary>
+        /// Tree controller constructor
+        /// </summary>
+        /// <param name="logger">Logger</param>
+        /// <param name="dataSourceService">Source Service for data</param>
         public TreeController(ILogger<TreeController> logger, IDataSourceService dataSourceService)
         {
             _authenticator = new Authenticator(this, Program.Configuration);
@@ -59,11 +67,23 @@ namespace Coscine.Api.Tree.Controllers
             _prefix = Program.Configuration.GetStringAndWait("coscine/global/epic/prefix");
         }
 
+        /// <summary>
+        /// Generates Id
+        /// </summary>
+        /// <param name="resourceId">Id of the resource</param>
+        /// <param name="path"> Path to file</param>
+        /// <returns> Uri </returns>
         public Uri GenerateId(string resourceId, string path)
         {
             return new Uri($"https://hdl.handle.net/{_prefix}/{resourceId}@path={Uri.EscapeDataString(path)}");
         }
 
+        /// <summary>
+        /// This method retrieves the metadata
+        /// </summary>
+        /// <param name="resourceId"> Id of a resource</param>
+        /// <param name="path">Path to the file</param>
+        /// <returns> JSON Object with the metadata if ok, otherwise Statuscode 400 or 401 or 404</returns>
         [HttpGet("[controller]/{resourceId}/{*path}")]
         public async Task<IActionResult> GetMetadata(string resourceId, string path)
         {
@@ -117,7 +137,7 @@ namespace Coscine.Api.Tree.Controllers
             var jObject = new JObject(
                 new JProperty("data", new JObject(
                     new JProperty("metadataStorage", JToken.FromObject(graphs)),
-                    new JProperty("fileStorage", JToken.FromObject(infos.Select( x => new ObjectMetaInfoReturnObject(x, _blobApiLink, resource.Id.ToString()))))
+                    new JProperty("fileStorage", JToken.FromObject(infos.Select(x => new ObjectMetaInfoReturnObject(x, _blobApiLink, resource.Id.ToString()))))
                     ))
                 );
 
@@ -125,6 +145,12 @@ namespace Coscine.Api.Tree.Controllers
             return Json(jObject);
         }
 
+        /// <summary>
+        /// This method stores the metadata of the file
+        /// </summary>
+        /// <param name="resourceId">Id of the resource</param>
+        /// <param name="path">Path to the file</param>
+        /// <returns>If ok Statuscode 204, otherwise Statuscode 400 or 401</returns>
         [HttpPut("[controller]/{resourceId}/{*path}")]
         public IActionResult StoreMetadataForFile(string resourceId, string path)
         {
@@ -238,7 +264,13 @@ namespace Coscine.Api.Tree.Controllers
             return NoContent();
 
         }
-
+        /// <summary>
+        /// Checks the resource Id and the path
+        /// </summary>
+        /// <param name="resourceId">Id of the resource</param>
+        /// <param name="path">Path to the file</param>
+        /// <param name="resource">Resource</param>
+        /// <returns>null, otherwise Statuscode  400 or 404 </returns>
         private IActionResult CheckResourceIdAndPath(string resourceId, string path, out Resource resource)
         {
             resource = null;
@@ -281,7 +313,11 @@ namespace Coscine.Api.Tree.Controllers
             // All good
             return null;
         }
-
+        /// <summary>
+        /// Gets the name of the resource type
+        /// </summary>
+        /// <param name="resource">Resource</param>
+        /// <returns> Processed name of the resource </returns>
         private string GetResourceTypeName(Resource resource)
         {
             if (resource.Type.DisplayName.ToLower().Equals("s3"))
@@ -293,7 +329,13 @@ namespace Coscine.Api.Tree.Controllers
                 return resource.Type.DisplayName.ToLower();
             }
         }
-
+        /// <summary>
+        /// Log analytics
+        /// </summary>
+        /// <param name="operation">Operation</param>
+        /// <param name="resourceId">Resource of the id</param>
+        /// <param name="filename">Name of the file</param>
+        /// <param name="user">User object</param>
         private void LogAnalytics(string operation, string resourceId, string filename, User user)
         {
             if (CoscineLoggerConfiguration.IsLogLevelActivated(LogType.Analytics))

src/Tree/Program.cs

@@ -3,8 +3,14 @@ using Coscine.Configuration;
 
 namespace Coscine.Api.Tree
 {
+    /// <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/Tree/Startup.cs

@@ -5,13 +5,22 @@ using System;
 
 namespace Coscine.Api.Tree
 {
+    /// <summary>
+    /// standard startup class
+    /// </summary>
     public class Startup : AbstractStartup
     {
+        /// <summary>
+        /// standard startup constructor
+        /// </summary>
         public Startup()
         {
 
         }
-
+        /// <summary>
+        /// Configures custom service extension
+        /// </summary>
+        /// <param name="services">Services</param>
         public override void ConfigureServicesExtension(IServiceCollection services)
         {
             base.ConfigureServicesExtension(services);

src/Tree/Tree.csproj

@@ -33,6 +33,7 @@
     <DefineConstants>DEBUG;TRACE</DefineConstants>
     <ErrorReport>prompt</ErrorReport>
     <WarningLevel>4</WarningLevel>
+	<DocumentationFile>bin\Debug\Coscine.Api.Tree.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\Release\Coscine.Api.Tree.xml</DocumentationFile>
   </PropertyGroup>
   <ItemGroup>
     <Reference Include="Consul, Version=0.7.2.6, Culture=neutral, PublicKeyToken=20a6ad9a81df1d95, processorArchitecture=MSIL">