From 5359beb9aa11bbab5cb91ee855b9bd3952eee932 Mon Sep 17 00:00:00 2001
From: ngfrolov <ng.frolov@autodrilling.ru>
Date: Thu, 14 Apr 2022 13:46:51 +0500
Subject: [PATCH] doc

---
 AsbCloudApp/AsbCloudApp.csproj                |  1 +
 AsbCloudApp/Data/AuthDto.cs                   | 10 +++++
 AsbCloudWebApi/AsbCloudWebApi.csproj          | 39 ++-----------------
 AsbCloudWebApi/Controllers/CrudController.cs  |  9 ++---
 .../WITS/WitsControllerAbstract.cs            | 30 +++++++++++++-
 .../Controllers/WITS/WitsInfoController.cs    | 10 +++++
 AsbCloudWebApi/DependencyInjection.cs         |  1 +
 7 files changed, 57 insertions(+), 43 deletions(-)

diff --git a/AsbCloudApp/AsbCloudApp.csproj b/AsbCloudApp/AsbCloudApp.csproj
index dbc15171..03763afd 100644
--- a/AsbCloudApp/AsbCloudApp.csproj
+++ b/AsbCloudApp/AsbCloudApp.csproj
@@ -2,6 +2,7 @@
 
   <PropertyGroup>
     <TargetFramework>net6.0</TargetFramework>
+	<GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
 </Project>
diff --git a/AsbCloudApp/Data/AuthDto.cs b/AsbCloudApp/Data/AuthDto.cs
index 648a876c..9235b40f 100644
--- a/AsbCloudApp/Data/AuthDto.cs
+++ b/AsbCloudApp/Data/AuthDto.cs
@@ -1,8 +1,18 @@
 namespace AsbCloudApp.Data
 {
+    /// <summary>
+    /// DTO для авторизации
+    /// </summary>
     public class AuthDto
     {
+        /// <summary>
+        /// Имя пользователя для входа
+        /// </summary>
         public string Login { get; set; }
+
+        /// <summary>
+        /// Пароль пользователя для входа
+        /// </summary>
         public string Password { get; set; }
     }
 }
diff --git a/AsbCloudWebApi/AsbCloudWebApi.csproj b/AsbCloudWebApi/AsbCloudWebApi.csproj
index 8d358003..92304360 100644
--- a/AsbCloudWebApi/AsbCloudWebApi.csproj
+++ b/AsbCloudWebApi/AsbCloudWebApi.csproj
@@ -7,24 +7,6 @@
 	<UserSecretsId>80899ceb-210f-4f19-ac56-aa90a5d666d4</UserSecretsId>
   </PropertyGroup>
 
-  <ItemGroup>
-    <Compile Remove="wwwroot\admin\**" />
-    <Content Remove="wwwroot\admin\**" />
-    <EmbeddedResource Remove="wwwroot\admin\**" />
-    <None Remove="wwwroot\admin\**" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <None Remove="AsbCloudWebApi.service" />
-    <None Remove="NetRest.service" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <Content Include="AsbCloudWebApi.service">
-      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
-    </Content>
-  </ItemGroup>
-
   <ItemGroup>
     <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="6.0.1" />
     <PackageReference Include="Microsoft.AspNetCore.SpaServices.Extensions" Version="6.0.1" />
@@ -40,24 +22,11 @@
   </ItemGroup>
 
   <ItemGroup>
-    <Content Update="wwwroot\asset-manifest.json">
-      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
-    </Content>
-    <Content Update="wwwroot\favicon.ico">
-      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
-    </Content>
-    <Content Update="wwwroot\index.html">
-      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
-    </Content>
-    <Content Update="wwwroot\manifest.json">
-      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
-    </Content>
-    <Content Update="wwwroot\robots.txt">
+    <Content Update="wwwroot\**">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </Content>
+	<Content Include="AsbCloudWebApi.service">
+	  <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+	</Content>
   </ItemGroup>
-
-  <ProjectExtensions><VisualStudio><UserProperties appsettings_1json__JsonSchema="" /></VisualStudio></ProjectExtensions>
-
-
 </Project>
diff --git a/AsbCloudWebApi/Controllers/CrudController.cs b/AsbCloudWebApi/Controllers/CrudController.cs
index 90724f32..ce22fd29 100644
--- a/AsbCloudWebApi/Controllers/CrudController.cs
+++ b/AsbCloudWebApi/Controllers/CrudController.cs
@@ -67,8 +67,7 @@ namespace AsbCloudWebApi.Controllers
         /// <returns>id</returns>
         [HttpPost]
         [Permission]
-        [ProducesResponseType(typeof(int), (int)System.Net.HttpStatusCode.OK)]
-        public virtual async Task<IActionResult> InsertAsync([FromBody] T value, CancellationToken token = default)
+        public virtual async Task<ActionResult<int>> InsertAsync([FromBody] T value, CancellationToken token = default)
         {
             if (InsertForbidAsync is not null && await InsertForbidAsync(value, token))
                 Forbid();
@@ -86,8 +85,7 @@ namespace AsbCloudWebApi.Controllers
         /// <returns>1 - успешно отредактировано, 0 - нет</returns>
         [HttpPut("{id}")]
         [Permission]
-        [ProducesResponseType(typeof(int), (int)System.Net.HttpStatusCode.OK)]
-        public virtual async Task<IActionResult> UpdateAsync(int id, [FromBody] T value, CancellationToken token = default)
+        public virtual async Task<ActionResult<int>> UpdateAsync(int id, [FromBody] T value, CancellationToken token = default)
         {
             if (UpdateForbidAsync is not null && await UpdateForbidAsync(id, value, token))
                 Forbid();
@@ -105,8 +103,7 @@ namespace AsbCloudWebApi.Controllers
         /// <param name="token"></param>
         /// <returns>1 - успешно удалено, 0 - нет</returns>
         [HttpDelete("{id}")]
-        [ProducesResponseType(typeof(int), (int)System.Net.HttpStatusCode.OK)]
-        public virtual async Task<IActionResult> DeleteAsync(int id, CancellationToken token = default)
+        public virtual async Task<ActionResult<int>> DeleteAsync(int id, CancellationToken token = default)
         {
             if (DeleteForbidAsync is not null && await DeleteForbidAsync(id, token))
                 Forbid();
diff --git a/AsbCloudWebApi/Controllers/WITS/WitsControllerAbstract.cs b/AsbCloudWebApi/Controllers/WITS/WitsControllerAbstract.cs
index 58c1aa2a..4badf829 100644
--- a/AsbCloudWebApi/Controllers/WITS/WitsControllerAbstract.cs
+++ b/AsbCloudWebApi/Controllers/WITS/WitsControllerAbstract.cs
@@ -31,6 +31,16 @@ namespace AsbCloudWebApi.Controllers.WITS
             this.telemetryHubContext = telemetryHubContext;
         }
 
+        /// <summary>
+        /// Метод для получения WITS записи от панели оператора.
+        /// Созраняет в БД.
+        /// Ретранслирует заинтересованным через SignalR.
+        /// </summary>
+        /// <param name="uid">уникальный идентификатор телеметрии</param>
+        /// <param name="dtos">WITS запись</param>
+        /// <param name="witsRecordRepository"></param>
+        /// <param name="token"></param>
+        /// <returns></returns>
         [HttpPost("{uid}")]
         [AllowAnonymous]
         public async virtual Task<IActionResult> PostDataAsync(
@@ -49,9 +59,17 @@ namespace AsbCloudWebApi.Controllers.WITS
             return Ok();
         }
 
+        /// <summary>
+        /// Получение списка архивных WITS записей за период.
+        /// </summary>
+        /// <param name="idWell">id скважины</param>
+        /// <param name="begin">начало диапазона</param>
+        /// <param name="end">конец диапазона</param>
+        /// <param name="witsRecordRepository"></param>
+        /// <param name="token"></param>
+        /// <returns></returns>
         [HttpGet("{idWell}")]
-        [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(IEnumerable<RecordBaseDto>))]
-        public async virtual Task<IActionResult> GetDataAsync(
+        public async virtual Task<ActionResult<IEnumerable<TDto>>> GetDataAsync(
             int idWell,
             DateTime begin,
             DateTime end,
@@ -65,6 +83,14 @@ namespace AsbCloudWebApi.Controllers.WITS
             return Ok(dtos);
         }
 
+        /// <summary>
+        /// Получение статистики по WITS записи.
+        /// Диапазон дат и общее количество записей.
+        /// </summary>
+        /// <param name="idWell">id скважины</param>
+        /// <param name="witsRecordRepository"></param>
+        /// <param name="token"></param>
+        /// <returns></returns>
         [HttpGet("{idWell}/datesRange")]
         [ProducesResponseType(StatusCodes.Status200OK, Type = typeof((DateTime begin, DateTime end, int count)?))]
         public async virtual Task<IActionResult> GetDatesRangeAsync(
diff --git a/AsbCloudWebApi/Controllers/WITS/WitsInfoController.cs b/AsbCloudWebApi/Controllers/WITS/WitsInfoController.cs
index bdb1b828..df602712 100644
--- a/AsbCloudWebApi/Controllers/WITS/WitsInfoController.cs
+++ b/AsbCloudWebApi/Controllers/WITS/WitsInfoController.cs
@@ -1,5 +1,7 @@
 using AsbCloudInfrastructure.Services;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
+using System.Collections.Generic;
 
 namespace AsbCloudWebApi.Controllers.WITS
 {
@@ -14,7 +16,12 @@ namespace AsbCloudWebApi.Controllers.WITS
             this.witsInfoService = witsInfoService;
         }
 
+        /// <summary>
+        /// Список всех WITS items для всех известных records
+        /// </summary>
+        /// <returns></returns>
         [HttpGet("item")]
+        [ProducesResponseType(typeof(IEnumerable<object>), (int)System.Net.HttpStatusCode.OK)]
         public IActionResult GetItems()
         {
             var result = witsInfoService.GetItems();
@@ -22,6 +29,7 @@ namespace AsbCloudWebApi.Controllers.WITS
         }
 
         [HttpGet("item/{idRecord}")]
+        [ProducesResponseType(typeof(IEnumerable<object>), (int)System.Net.HttpStatusCode.OK)]
         public IActionResult GetItems(int idRecord)
         {
             var result = witsInfoService.GetItems(idRecord);
@@ -29,6 +37,7 @@ namespace AsbCloudWebApi.Controllers.WITS
         }
 
         [HttpGet("record")]
+        [ProducesResponseType(typeof(IEnumerable<object>), (int)System.Net.HttpStatusCode.OK)]
         public IActionResult GetRecordInfo()
         {
             var result = witsInfoService.GetRecords();
@@ -36,6 +45,7 @@ namespace AsbCloudWebApi.Controllers.WITS
         }
 
         [HttpGet("record/{idRecord}")]
+        [ProducesResponseType(typeof(IEnumerable<object>), (int)System.Net.HttpStatusCode.OK)]
         public IActionResult GetRecordInfo(int idRecord)
         {
             var result = witsInfoService.GetRecords(idRecord);
diff --git a/AsbCloudWebApi/DependencyInjection.cs b/AsbCloudWebApi/DependencyInjection.cs
index ca79e085..bc818660 100644
--- a/AsbCloudWebApi/DependencyInjection.cs
+++ b/AsbCloudWebApi/DependencyInjection.cs
@@ -54,6 +54,7 @@ namespace AsbCloudWebApi
                 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                 c.IncludeXmlComments(xmlPath);
+                c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "AsbCloudApp.xml"));
 
             });
         }