settings: added api descriptions

This commit is contained in:
Natalia Ovchinnikova 2023-03-10 18:31:08 +03:00
parent 152bacc80b
commit bf5ab933a9

View File

@ -129,8 +129,19 @@ public class SettingsController : BaseSettingsController
_customColorThemesSettingsHelper = customColorThemesSettingsHelper;
_quotaUsageManager = quotaUsageManager;
_tenantDomainValidator = tenantDomainValidator;
}
}
/// <summary>
/// Returns a list of all the available portal settings with the current values for each parameter.
/// </summary>
/// <short>
/// Get the portal settings
/// </short>
/// <category>Common settings</category>
/// <param name="withpassword">Specifies if the password hasher settings will be returned or not</param>
/// <returns>Settings</returns>
/// <path>api/2.0/settings</path>
/// <httpMethod>GET</httpMethod>
[HttpGet("")]
[AllowNotPayment, AllowSuspended, AllowAnonymous]
public SettingsDto GetSettings(bool? withpassword)
@ -223,6 +234,17 @@ public class SettingsController : BaseSettingsController
return settings;
}
/// <summary>
/// Saves the mail domain settings specified in the request to the portal.
/// </summary>
/// <short>
/// Save the mail domain settings
/// </short>
/// <category>Common settings</category>
/// <param name="inDto">Mail domain settings: trusted domain type, list of domains, invites as a user or not</param>
/// <returns>Message about the result of saving the mail domain settings</returns>
/// <path>api/2.0/settings/maildomainsettings</path>
/// <httpMethod>POST</httpMethod>
[HttpPost("maildomainsettings")]
public object SaveMailDomainSettings(MailDomainSettingsRequestsDto inDto)
{
@ -257,14 +279,35 @@ public class SettingsController : BaseSettingsController
_messageService.Send(MessageAction.TrustedMailDomainSettingsUpdated);
return Resource.SuccessfullySaveSettingsMessage;
}
}
/// <summary>
/// Returns the space usage quota for the portal with the specified space usage for each module.
/// </summary>
/// <short>
/// Get the space usage
/// </short>
/// <category>Quota</category>
/// <returns>Space usage and limits for upload</returns>
/// <path>api/2.0/settings/quota</path>
/// <httpMethod>GET</httpMethod>
[HttpGet("quota")]
public async Task<QuotaUsageDto> GetQuotaUsed()
{
return await _quotaUsageManager.Get();
}
/// <summary>
/// Saves the user quota settings specified in the request to the current portal.
/// </summary>
/// <short>
/// Save the user quota settings
/// </short>
/// <category>Quota</category>
/// <param name="inDto">The user quota settings: enabled or not, default user quota</param>
/// <returns>Message about the result of saving the user quota settings</returns>
/// <path>api/2.0/settings/userquotasettings</path>
/// <httpMethod>POST</httpMethod>
[HttpPost("userquotasettings")]
public object SaveUserQuotaSettings(UserQuotaSettingsRequestsDto inDto)
{
@ -273,8 +316,16 @@ public class SettingsController : BaseSettingsController
_settingsManager.Save(new TenantUserQuotaSettings { EnableUserQuota = inDto.EnableUserQuota, DefaultUserQuota = inDto.DefaultUserQuota });
return Resource.SuccessfullySaveSettingsMessage;
}
}
/// <summary>
/// Returns a list of all the available portal languages in the format of a two-letter or four-letter language code (e.g. "de", "en-US", etc.).
/// </summary>
/// <short>Get supporrted languages</short>
/// <category>Common settings</category>
/// <returns>List of all the available portal languages</returns>
/// <path>api/2.0/settings/cultures</path>
/// <httpMethod>GET</httpMethod>
[AllowAnonymous]
[AllowNotPayment]
[HttpGet("cultures")]
@ -283,6 +334,14 @@ public class SettingsController : BaseSettingsController
return _setupInfo.EnabledCultures.Select(r => r.Name).OrderBy(s => s).ToArray();
}
/// <summary>
/// Returns a list of all the available portal time zones.
/// </summary>
/// <short>Get time zones</short>
/// <category>Common settings</category>
/// <returns>List of all the available time zones</returns>
/// <path>api/2.0/settings/timezones</path>
/// <httpMethod>GET</httpMethod>
[Authorize(AuthenticationSchemes = "confirm", Roles = "Wizard,Administrators")]
[HttpGet("timezones")]
[AllowNotPayment]
@ -310,6 +369,14 @@ public class SettingsController : BaseSettingsController
return listOfTimezones;
}
/// <summary>
/// Returns the portal hostname.
/// </summary>
/// <short>Get hostname</short>
/// <category>Common settings</category>
/// <returns>Portal hostname</returns>
/// <path>api/2.0/settings/machine</path>
/// <httpMethod>GET</httpMethod>
[Authorize(AuthenticationSchemes = "confirm", Roles = "Wizard")]
[HttpGet("machine")]
[AllowNotPayment]
@ -318,32 +385,80 @@ public class SettingsController : BaseSettingsController
return Dns.GetHostName().ToLowerInvariant();
}
/// <summary>
/// Saves the DNS settings specified in the request to the current portal.
/// </summary>
/// <short>Save the DNS settings</short>
/// <category>Common settings</category>
/// <param name="model">DNS settings: DNS, enabled or not</param>
/// <returns>Message about changing DNS</returns>
/// <path>api/2.0/settings/dns</path>
/// <httpMethod>PUT</httpMethod>
[HttpPut("dns")]
public object SaveDnsSettings(DnsSettingsRequestsDto model)
{
return _dnsSettings.SaveDnsSettings(model.DnsName, model.Enable);
}
/// <summary>
/// Starts the process of recalculating quota.
/// </summary>
/// <short>
/// Recalculate quota
/// </short>
/// <category>Quota</category>
/// <path>api/2.0/settings/recalculatequota</path>
/// <httpMethod>GET</httpMethod>
/// <returns></returns>
[HttpGet("recalculatequota")]
public void RecalculateQuota()
{
_permissionContext.DemandPermissions(SecutiryConstants.EditPortalSettings);
_quotaSyncOperation.RecalculateQuota(_tenantManager.GetCurrentTenant());
}
}
/// <summary>
/// Checks the process of recalculating quota.
/// </summary>
/// <short>
/// Check quota recalculation
/// </short>
/// <category>Quota</category>
/// <returns>Boolean value: true - quota recalculation process is enabled, false - quota recalculation process is disabled</returns>
/// <path>api/2.0/settings/checkrecalculatequota</path>
/// <httpMethod>GET</httpMethod>
[HttpGet("checkrecalculatequota")]
public bool CheckRecalculateQuota()
{
_permissionContext.DemandPermissions(SecutiryConstants.EditPortalSettings);
return _quotaSyncOperation.CheckRecalculateQuota(_tenantManager.GetCurrentTenant());
}
}
/// <summary>
/// Returns the portal logo image URL.
/// </summary>
/// <short>
/// Get a portal logo
/// </short>
/// <category>Common settings</category>
/// <returns>Portal logo image URL</returns>
/// <path>api/2.0/settings/logo</path>
/// <httpMethod>GET</httpMethod>
[HttpGet("logo")]
public object GetLogo()
{
return _tenantInfoSettingsHelper.GetAbsoluteCompanyLogoPath(_settingsManager.Load<TenantInfoSettings>());
}
}
/// <summary>
/// Completes the Wizard settings.
/// </summary>
/// <short>Complete the Wizard settings</short>
/// <category>Wizard</category>
/// <param name="inDto">Wizard settings: email, password hash, language, time zone, AMI ID, subscribed from the site or not</param>
/// <returns>Wizard settings</returns>
/// <path>api/2.0/settings/wizard/complete</path>
/// <httpMethod>PUT</httpMethod>
[AllowNotPayment]
[HttpPut("wizard/complete")]
[Authorize(AuthenticationSchemes = "confirm", Roles = "Wizard")]
@ -354,8 +469,16 @@ public class SettingsController : BaseSettingsController
_permissionContext.DemandPermissions(SecutiryConstants.EditPortalSettings);
return _firstTimeTenantSettings.SaveData(inDto);
}
}
/// <summary>
/// Closes the welcome pop-up notification.
/// </summary>
/// <short>Close the welcome pop-up notification</short>
/// <category>Common settings</category>
/// <returns></returns>
/// <path>api/2.0/settings/welcome/close</path>
/// <httpMethod>PUT</httpMethod>
///<visible>false</visible>
[HttpPut("welcome/close")]
public void CloseWelcomePopup()
@ -373,13 +496,30 @@ public class SettingsController : BaseSettingsController
_settingsManager.SaveForCurrentUser(collaboratorPopupSettings);
}
/// <summary>
/// Returns the portal color theme.
/// </summary>
/// <short>Get a color theme</short>
/// <category>Common settings</category>
/// <returns>Settings of the portal themes</returns>
/// <path>api/2.0/settings/colortheme</path>
/// <httpMethod>GET</httpMethod>
[AllowAnonymous, AllowNotPayment, AllowSuspended]
[HttpGet("colortheme")]
public CustomColorThemesSettingsDto GetColorTheme()
{
return new CustomColorThemesSettingsDto(_settingsManager.Load<CustomColorThemesSettings>(), _customColorThemesSettingsHelper.Limit);
}
/// <summary>
/// Saves the portal color theme specified in the request.
/// </summary>
/// <short>Save a color theme</short>
/// <category>Common settings</category>
/// <param name="inDto">Portal theme settings</param>
/// <returns>Settings of the portal themes</returns>
/// <path>api/2.0/settings/colortheme</path>
/// <httpMethod>PUT</httpMethod>
[HttpPut("colortheme")]
public CustomColorThemesSettingsDto SaveColorTheme(CustomColorThemesSettingsRequestsDto inDto)
{
@ -446,6 +586,15 @@ public class SettingsController : BaseSettingsController
return new CustomColorThemesSettingsDto(settings, _customColorThemesSettingsHelper.Limit);
}
/// <summary>
/// Deletes the portal color theme with the ID specified in the request.
/// </summary>
/// <short>Delete a color theme</short>
/// <category>Common settings</category>
/// <param name="id">Portal theme ID</param>
/// <returns>Settings of the portal themes</returns>
/// <path>api/2.0/settings/colortheme</path>
/// <httpMethod>DELETE</httpMethod>
[HttpDelete("colortheme")]
public CustomColorThemesSettingsDto DeleteColorTheme(int id)
{
@ -471,6 +620,14 @@ public class SettingsController : BaseSettingsController
return new CustomColorThemesSettingsDto(settings, _customColorThemesSettingsHelper.Limit);
}
/// <summary>
/// Closes the admin helper notification.
/// </summary>
/// <short>Close the admin helper notification</short>
/// <category>Common settings</category>
/// <returns></returns>
/// <path>api/2.0/settings/closeadminhelper</path>
/// <httpMethod>PUT</httpMethod>
[HttpPut("closeadminhelper")]
public void CloseAdminHelper()
{
@ -483,7 +640,16 @@ public class SettingsController : BaseSettingsController
adminHelperSettings.Viewed = true;
_settingsManager.SaveForCurrentUser(adminHelperSettings);
}
/// <summary>
/// Sets the portal time zone and language specified in the request.
/// </summary>
/// <short>Set time zone and language</short>
/// <category>Common settings</category>
/// <param name="inDto">Settings request parameters: language, time zone ID</param>
/// <returns>Message about the operation result</returns>
/// <path>api/2.0/settings/timeandlanguage</path>
/// <httpMethod>PUT</httpMethod>
///<visible>false</visible>
[HttpPut("timeandlanguage")]
public object TimaAndLanguage(SettingsRequestsDto inDto)
@ -526,7 +692,16 @@ public class SettingsController : BaseSettingsController
return Resource.SuccessfullySaveSettingsMessage;
}
/// <summary>
/// Sets the default product page.
/// </summary>
/// <short>Set the default product page</short>
/// <category>Common settings</category>
/// <param name="inDto">Settings request parameters: default product ID</param>
/// <returns>Message about the operation result</returns>
/// <path>api/2.0/settings/defaultpage</path>
/// <httpMethod>PUT</httpMethod>
///<visible>false</visible>
[HttpPut("defaultpage")]
public object SaveDefaultPageSetting(SettingsRequestsDto inDto)
@ -538,15 +713,33 @@ public class SettingsController : BaseSettingsController
_messageService.Send(MessageAction.DefaultStartPageSettingsUpdated);
return Resource.SuccessfullySaveSettingsMessage;
}
}
/// <summary>
/// Updates the email activation settings.
/// </summary>
/// <short>Update the email activation settings</short>
/// <category>Common settings</category>
/// <param name="settings">Email activation settings: shown or hidden, guid ID</param>
/// <returns>Updated email activation settings</returns>
/// <path>api/2.0/settings/emailactivation</path>
/// <httpMethod>PUT</httpMethod>
[HttpPut("emailactivation")]
public EmailActivationSettings UpdateEmailActivationSettings(EmailActivationSettings settings)
{
_settingsManager.SaveForCurrentUser(settings);
return settings;
}
}
/// <summary>
/// Returns the space usage statistics of the module with the ID specified in the request.
/// </summary>
/// <category>Statistics</category>
/// <short>Get the space usage statistics</short>
/// <param name="id">Module ID</param>
/// <returns>Module space usage statistics</returns>
/// <path>api/2.0/settings/statistics/spaceusage/{id}</path>
/// <httpMethod>GET</httpMethod>
[HttpGet("statistics/spaceusage/{id}")]
public Task<List<UsageSpaceStatItemDto>> GetSpaceUsageStatistics(Guid id)
{
@ -579,8 +772,18 @@ public class SettingsController : BaseSettingsController
Size = FileSizeComment.FilesSizeToString(it.SpaceUsage),
Url = it.Url
});
}
}
/// <summary>
/// Returns the user visit statistics for the period specified in the request.
/// </summary>
/// <category>Statistics</category>
/// <short>Get the visit statistics</short>
/// <param name="fromDate">Start period date</param>
/// <param name="toDate">End period date</param>
/// <returns>List of point charts</returns>
/// <path>api/2.0/settings/statistics/visit</path>
/// <httpMethod>GET</httpMethod>
[HttpGet("statistics/visit")]
public List<ChartPointDto> GetVisitStatistics(ApiDateTime fromDate, ApiDateTime toDate)
{
@ -633,8 +836,16 @@ public class SettingsController : BaseSettingsController
}
return points;
}
}
/// <summary>
/// Returns the socket settings.
/// </summary>
/// <category>Common settings</category>
/// <short>Get the socket settings</short>
/// <path>api/2.0/settings/socket</path>
/// <httpMethod>GET</httpMethod>
/// <returns>Socket settings</returns>
[HttpGet("socket")]
public object GetSocketSettings()
{
@ -648,15 +859,31 @@ public class SettingsController : BaseSettingsController
}
return new { Url = hubUrl };
}
/*///<visible>false</visible>
}
/*/// <summary>
/// Returns the tenant Control Panel settings.
/// </summary>
/// <category>Common settings</category>
/// <short>Get the tenant Control Panel settings</short>
/// <returns>Tenant Control Panel settings</returns>
/// <path>api/2.0/settings/controlpanel</path>
/// <httpMethod>GET</httpMethod>
///<visible>false</visible>
[HttpGet("controlpanel")]
public TenantControlPanelSettings GetTenantControlPanelSettings()
{
return _settingsManager.Load<TenantControlPanelSettings>();
}*/
}*/
/// <summary>
/// Returns the authorization services.
/// </summary>
/// <category>Authorization</category>
/// <short>Get the authorization services</short>
/// <path>api/2.0/settings/authservice</path>
/// <httpMethod>GET</httpMethod>
/// <returns>Authorization services</returns>
[HttpGet("authservice")]
public IEnumerable<AuthServiceRequestsDto> GetAuthServices()
{
@ -667,6 +894,15 @@ public class SettingsController : BaseSettingsController
.ToList();
}
/// <summary>
/// Saves the authorization keys.
/// </summary>
/// <category>Authorization</category>
/// <short>Save the authorization keys</short>
/// <param name="inDto">Authorization service parameters: name, title, description, instruction, can be set or not, list of authorization keys</param>
/// <path>api/2.0/settings/authservice</path>
/// <httpMethod>POST</httpMethod>
/// <returns>Boolean value: true if the authorization keys are changed</returns>
[HttpPost("authservice")]
public bool SaveAuthKeys(AuthServiceRequestsDto inDto)
{
@ -732,6 +968,14 @@ public class SettingsController : BaseSettingsController
return changed;
}
/// <summary>
/// Returns the portal payment settings.
/// </summary>
/// <category>Common settings</category>
/// <short>Get the payment settings</short>
/// <path>api/2.0/settings/payment</path>
/// <httpMethod>GET</httpMethod>
/// <returns>Payment settings</returns>
[AllowNotPayment]
[HttpGet("payment")]
public object PaymentSettings()
@ -763,10 +1007,13 @@ public class SettingsController : BaseSettingsController
/// <visible>false</visible>
/// <summary>
/// Gets a link that will connect TelegramBot to your account
/// Returns a link that will connect TelegramBot to your account.
/// </summary>
/// <returns>url</returns>
///
/// <category>Telegram</category>
/// <short>Get the Telegram link</short>
/// <path>api/2.0/settings/telegramlink</path>
/// <httpMethod>GET</httpMethod>
/// <returns>Telegram link</returns>
[HttpGet("telegramlink")]
public object TelegramLink()
{
@ -782,11 +1029,15 @@ public class SettingsController : BaseSettingsController
return currentLink;
}
}
/// <summary>
/// Checks if user has connected TelegramBot
/// Checks if the user has connected to TelegramBot.
/// </summary>
/// <returns>0 - not connected, 1 - connected, 2 - awaiting confirmation</returns>
/// <category>Telegram</category>
/// <short>Check the Telegram connection</short>
/// <path>api/2.0/settings/telegramisconnected</path>
/// <httpMethod>GET</httpMethod>
/// <returns>Operation result: 0 - not connected, 1 - connected, 2 - awaiting confirmation</returns>
[HttpGet("telegramisconnected")]
public object TelegramIsConnected()
{
@ -794,8 +1045,13 @@ public class SettingsController : BaseSettingsController
}
/// <summary>
/// Unlinks TelegramBot from your account
/// </summary>
/// Unlinks TelegramBot from your account.
/// </summary>
/// <category>Telegram</category>
/// <short>Unlink Telegram</short>
/// <path>api/2.0/settings/telegramdisconnect</path>
/// <httpMethod>DELETE</httpMethod>
/// <returns></returns>
[HttpDelete("telegramdisconnect")]
public void TelegramDisconnect()
{