Add swagger doc to app-settings.js

apps/app/src/server/routes/apiv3/app-settings.js

@@ -17,6 +17,7 @@ const express = require('express');
 
 const router = express.Router();
 
+
 /**
  * @swagger
  *
@@ -26,21 +27,133 @@ const router = express.Router();
  *        description: AppSettingParams
  *        type: object
  *        properties:
+ *          azureReferenceFileWithRelayMode:
+ *            type: boolean
+ *            example: false
+ *          azureUseOnlyEnvVars:
+ *            type: boolean
+ *            example: false
+ *          confidential:
+ *            type: string
+ *            description: confidential show on page header
+ *            example: 'GROWI'
+ *          envAzureClientId:
+ *            type: string
+ *            example: 'AZURE_CLIENT_ID'
+ *          envAzureClientSecret:
+ *            type: string
+ *            example: 'AZURE_CLIENT_SECRET'
+ *          envAzureStorageAccountName:
+ *           type: string
+ *           example: 'AZURE_STORAGE_ACCOUNT_NAME'
+ *          envAzureStorageContainerName:
+ *            type: string
+ *            example: 'AZURE_STORAGE_CONTAINER_NAME'
+ *          envFileUploadType:
+ *            type: string
+ *            example: 'mongodb'
+ *          envGcsApiKeyJsonPath:
+ *            type: string
+ *            example: 'GCS_API_KEY_JSON_PATH'
+ *          envGcsBucket:
+ *            type: string
+ *            example: 'GCS_BUCKET'
+ *          envGcsUploadNamespace:
+ *            type: string
+ *            example: 'GCS_UPLOAD_NAMESPACE'
+ *          envSiteUrl:
+ *            type: string
+ *            example: 'http://localhost:3000'
+ *          fileUpload:
+ *            type: boolean
+ *            example: true
+ *          fileUploadType:
+ *            type: string
+ *            example: 'local'
+ *          fromAddress:
+ *            type: string
+ *            example: info@growi.org
+ *          gcsApiKeyJsonPath:
+ *            type: string
+ *            example: 'GCS_API_KEY_JSON_PATH'
+ *          gcsBucket:
+ *            type: string
+ *            example: 'GCS_BUCKET'
+ *          gcsReferenceFileWithRelayMode:
+ *            type: boolean
+ *            example: false
+ *          gcsUploadNamespace:
+ *            type: string
+ *            example: 'GCS_UPLOAD_NAMESPACE'
+ *          gcsUseOnlyEnvVars:
+ *            type: boolean
+ *            example: false
+ *          globalLang:
+ *            type: string
+ *            example: 'ja_JP'
+ *          isAppSiteUrlHashed:
+ *            type: boolean
+ *            example: false
+ *          isEmailPublishedForNewUser:
+ *            type: boolean
+ *            example: true
+ *          isMaintenanceMode:
+ *            type: boolean
+ *            example: false
+ *          isQuestionnaireEnabled:
+ *            type: boolean
+ *            example: true
+ *          isV5Compatible:
+ *            type: boolean
+ *            example: true
+ *          s3AccessKeyId:
+ *            type: string
+ *          s3Bucket:
+ *            type: string
+ *          s3CustomEndpoint:
+ *            type: string
+ *          s3ReferenceFileWithRelayMode:
+ *            type: boolean
+ *          s3Region:
+ *            type: string
+ *          siteUrl:
+ *            type: string
+ *          siteUrlUseOnlyEnvVars:
+ *            type: boolean
+ *          smtpHost:
+ *            type: string
+ *          smtpPassword:
+ *            type: string
+ *          smtpPort:
+ *            type: string
+ *          smtpUser:
+ *            type: string
+ *          useOnlyEnvVarForFileUploadType:
+ *            type: boolean
+ *      AppSettingPutParams:
+ *        description: AppSettingPutParams
+ *        type: object
+ *        properties:
  *          title:
  *            type: string
- *            description: site name show on page header and tilte of HTML
+ *            description: title of the site
+ *            example: 'GROWI'
  *          confidential:
  *            type: string
  *            description: confidential show on page header
+ *            example: 'GROWI'
  *          globalLang:
  *            type: string
- *            description: language set when create user
+ *            description: global language
+ *            example: 'ja_JP'
  *          isEmailPublishedForNewUser:
  *            type: boolean
- *            description: default email show/hide setting when create user
+ *            description: is email published for new user, or not
+ *            example: true
  *          fileUpload:
  *            type: boolean
- *            description: enable upload file except image file
+ *            description: is file upload enabled, or not
+ *            example: true
  *      SiteUrlSettingParams:
  *        description: SiteUrlSettingParams
  *        type: object
@@ -51,40 +164,96 @@ const router = express.Router();
  *          envSiteUrl:
  *            type: string
  *            description: environment variable 'APP_SITE_URL'
- *      MailSetting:
- *        description: MailSettingParams
+ *      SmtpSettingParams:
+ *        description: SmtpSettingParams
  *        type: object
  *        properties:
- *          fromAddress:
+ *          smtpHost:
  *            type: string
- *            description: e-mail address used as from address of mail which sent from GROWI app
- *          transmissionMethod:
+ *            description: host name of client's smtp server
+ *            example: 'smtp.example.com'
+ *          smtpPort:
  *            type: string
- *            description: transmission method
- *      SmtpSettingParams:
- *        description: SmtpSettingParams
+ *            description: port of client's smtp server
+ *            example: '587'
+ *          smtpUser:
+ *            type: string
+ *            description: user name of client's smtp server
+ *            example: 'USER'
+ *          smtpPassword:
+ *            type: string
+ *            description: password of client's smtp server
+ *            example: 'PASSWORD'
+ *          fromAddress:
+ *            type: string
+ *            description: e-mail address
+ *            example: 'info@example.com'
+ *      SmtpSettingResponseParams:
+ *        description: SmtpSettingResponseParams
  *        type: object
  *        properties:
+ *          isMailerSetup:
+ *            type: boolean
+ *            description: is mailer setup, or not
+ *            example: true
  *          smtpHost:
  *            type: string
  *            description: host name of client's smtp server
+ *            example: 'smtp.example.com'
  *          smtpPort:
  *            type: string
  *            description: port of client's smtp server
+ *            example: '587'
  *          smtpUser:
  *            type: string
  *            description: user name of client's smtp server
+ *            example: 'USER'
  *          smtpPassword:
  *            type: string
  *            description: password of client's smtp server
+ *            example: 'PASSWORD'
+ *          fromAddress:
+ *            type: string
+ *            description: e-mail address
+ *            example: 'info@example.com'
  *      SesSettingParams:
  *        description: SesSettingParams
  *        type: object
  *        properties:
- *          accessKeyId:
+ *          from:
+ *            type: string
+ *            description: e-mail address used as from address of mail which sent from GROWI app
+ *            example: 'info@growi.org'
+ *          transmissionMethod:
+ *            type: string
+ *            description: transmission method
+ *            example: 'ses'
+ *          sesAccessKeyId:
+ *            type: string
+ *            description: accesskey id for authentification of AWS
+ *          sesSecretAccessKey:
+ *            type: string
+ *            description: secret key for authentification of AWS
+ *      SesSettingResponseParams:
+ *        description: SesSettingParams
+ *        type: object
+ *        properties:
+ *          isMailerSetup:
+ *            type: boolean
+ *            description: is mailer setup, or not
+ *            example: true
+ *          from:
+ *            type: string
+ *            description: e-mail address used as from address of mail which sent from GROWI app
+ *            example: 'info@growi.org'
+ *          transmissionMethod:
+ *            type: string
+ *            description: transmission method
+ *            example: 'ses'
+ *          sesAccessKeyId:
  *            type: string
  *            description: accesskey id for authentification of AWS
- *          secretAccessKey:
+ *          sesSecretAccessKey:
  *            type: string
  *            description: secret key for authentification of AWS
  *      FileUploadSettingParams:
@@ -124,22 +293,35 @@ const router = express.Router();
  *          gcsReferenceFileWithRelayMode:
  *            type: boolean
  *            description: is enable internal stream system for gcs file request
- *          envGcsApiKeyJsonPath:
+ *          azureTenantId:
  *            type: string
- *            description: Path of the JSON file that contains service account key to authenticate to GCP API
- *          envGcsBucket:
+ *            description: tenant id of azure
+ *          azureClientId:
  *            type: string
- *            description: Name of the GCS bucket
- *          envGcsUploadNamespace:
+ *            description: client id of azure
+ *          azureClientSecret:
+ *            type: string
+ *            description: client secret of azure
+ *          azureStorageAccountName:
  *            type: string
- *            description: Directory name to create in the bucket
- *      PluginSettingParams:
- *        description: PluginSettingParams
+ *            description: storage account name of azure
+ *          azureStorageContainerName:
+ *            type: string
+ *            description: storage container name of azure
+ *          azureReferenceFileWithRelayMode:
+ *            type: boolean
+ *            description: is enable internal stream system for azure file request
+ *      QuestionnaireSettingParams:
+ *        description: QuestionnaireSettingParams
  *        type: object
  *        properties:
- *          isEnabledPlugins:
- *            type: string
- *            description: enable use plugins
+ *          isQuestionnaireEnabled:
+ *            type: boolean
+ *            description: is questionnaire enabled, or not
+ *            example: true
+ *          isAppSiteUrlHashed:
+ *            type: boolean
+ *            description: is app site url hashed, or not
  */
 
 module.exports = (crowi) => {
@@ -225,7 +407,7 @@ module.exports = (crowi) => {
    *                  properties:
    *                    appSettingsParams:
    *                      type: object
-   *                      description: app settings params
+   *                      $ref: '#/components/schemas/AppSettingParams'
    */
   router.get('/', accessTokenParser, loginRequiredStrictly, adminRequired, async(req, res) => {
     const appSettingsParams = {
@@ -309,14 +491,18 @@ module.exports = (crowi) => {
    *          content:
    *            application/json:
    *              schema:
-   *                $ref: '#/components/schemas/AppSettingParams'
+   *                $ref: '#/components/schemas/AppSettingPutParams'
    *        responses:
    *          200:
    *            description: Succeeded to update app setting
    *            content:
    *              application/json:
    *                schema:
-   *                  $ref: '#/components/schemas/AppSettingParams'
+   *                  type: object
+   *                  properties:
+   *                    appSettingParams:
+   *                      type: object
+   *                      $ref: '#/components/schemas/AppSettingPutParams'
    */
   router.put('/app-setting', loginRequiredStrictly, adminRequired, addActivity, validator.appSetting, apiV3FormValidator, async(req, res) => {
     const requestAppSettingParams = {
@@ -371,7 +557,15 @@ module.exports = (crowi) => {
    *            content:
    *              application/json:
    *                schema:
-   *                  $ref: '#/components/schemas/SiteUrlSettingParams'
+   *                  type: object
+   *                  properties:
+   *                    siteUrlSettingParams:
+   *                      type: object
+   *                      properties:
+   *                        siteUrl:
+   *                          type: string
+   *                          description: Site URL. e.g. https://example.com, https://example.com:3000
+   *                          example: 'http://localhost:3000'
    */
   router.put('/site-url-setting', loginRequiredStrictly, adminRequired, addActivity, validator.siteUrlSetting, apiV3FormValidator, async(req, res) => {
 
@@ -513,7 +707,11 @@ module.exports = (crowi) => {
    *            content:
    *              application/json:
    *                schema:
-   *                  $ref: '#/components/schemas/SmtpSettingParams'
+   *                  type: object
+   *                  properties:
+   *                    mailSettingParams:
+   *                      type: object
+   *                      $ref: '#/components/schemas/SmtpSettingResponseParams'
    */
   router.put('/smtp-setting', loginRequiredStrictly, adminRequired, addActivity, validator.smtpSetting, apiV3FormValidator, async(req, res) => {
     const requestMailSettingParams = {
@@ -550,6 +748,11 @@ module.exports = (crowi) => {
    *        responses:
    *          200:
    *            description: Succeeded to send test mail for smtp
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  type: object
+   *                  description: Empty object
    */
   router.post('/smtp-test', loginRequiredStrictly, adminRequired, addActivity, async(req, res) => {
     try {
@@ -587,7 +790,7 @@ module.exports = (crowi) => {
    *            content:
    *              application/json:
    *                schema:
-   *                  $ref: '#/components/schemas/SesSettingParams'
+   *                  $ref: '#/components/schemas/SesSettingResponseParams'
    */
   router.put('/ses-setting', loginRequiredStrictly, adminRequired, addActivity, validator.sesSetting, apiV3FormValidator, async(req, res) => {
     const { mailService } = crowi;
@@ -637,7 +840,11 @@ module.exports = (crowi) => {
    *            content:
    *              application/json:
    *                schema:
-   *                  $ref: '#/components/schemas/FileUploadSettingParams'
+   *                  type: object
+   *                  properties:
+   *                    responseParams:
+   *                      type: object
+   *                      $ref: '#/components/schemas/FileUploadSettingParams'
    */
   //  eslint-disable-next-line max-len
   router.put('/file-upload-setting', loginRequiredStrictly, adminRequired, addActivity, validator.fileUploadSetting, apiV3FormValidator, async(req, res) => {
@@ -721,6 +928,33 @@ module.exports = (crowi) => {
 
   });
 
+  /**
+   * @swagger
+   *
+   *    /app-settings/questionnaire-settings:
+   *      put:
+   *        tags: [AppSettings]
+   *        operationId: updateAppSettingQuestionnaireSettings
+   *        summary: /app-settings/questionnaire-settings
+   *        description: Update QuestionnaireSetting
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                $ref: '#/components/schemas/QuestionnaireSettingParams'
+   *        responses:
+   *          200:
+   *            description: Succeeded to update QuestionnaireSetting
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  type: object
+   *                  properties:
+   *                    responseParams:
+   *                      type: object
+   *                      $ref: '#/components/schemas/QuestionnaireSettingParams'
+   */
   // eslint-disable-next-line max-len
   router.put('/questionnaire-settings', loginRequiredStrictly, adminRequired, addActivity, validator.questionnaireSettings, apiV3FormValidator, async(req, res) => {
     const { isQuestionnaireEnabled, isAppSiteUrlHashed } = req.body;
@@ -750,6 +984,34 @@ module.exports = (crowi) => {
 
   });
 
+  /**
+   * @swagger
+   *
+   *    /app-settings/v5-schema-migration:
+   *      post:
+   *        tags: [AppSettings]
+   *        operationId: updateAppSettingV5SchemaMigration
+   *        summary: AccessToken supported.
+   *        description: Update V5SchemaMigration
+   *        requestBody:
+   *          content:
+   *            application/json:
+   *              schema:
+   *                type: object
+   *                properties:
+   *        responses:
+   *          200:
+   *            description: Succeeded to get V5SchemaMigration
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  type: object
+   *                  properties:
+   *                    isV5Compatible:
+   *                      type: boolean
+   *                      description: is V5 compatible, or not
+   *                      example: true
+   */
   router.post('/v5-schema-migration', accessTokenParser, loginRequiredStrictly, adminRequired, async(req, res) => {
     const isMaintenanceMode = crowi.appService.isMaintenanceMode();
     if (!isMaintenanceMode) {
@@ -771,6 +1033,37 @@ module.exports = (crowi) => {
     return res.apiv3({ isV5Compatible });
   });
 
+  /**
+   * @swagger
+   *
+   *    /app-settings/maintenance-mode:
+   *      post:
+   *        tags: [AppSettings]
+   *        operationId: updateAppSettingMaintenanceMode
+   *        summary: AccessToken supported.
+   *        description: Update MaintenanceMode
+   *        requestBody:
+   *          content:
+   *            application/json:
+   *              schema:
+   *                type: object
+   *                properties:
+   *                  flag:
+   *                    type: boolean
+   *                    description: flag for maintenance mode
+   *        responses:
+   *          200:
+   *            description: Succeeded to update MaintenanceMode
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  type: object
+   *                  properties:
+   *                    flag:
+   *                      type: boolean
+   *                      description: true if maintenance mode is enabled
+   *                      example: true
+   */
   // eslint-disable-next-line max-len
   router.post('/maintenance-mode', accessTokenParser, loginRequiredStrictly, adminRequired, addActivity, validator.maintenanceMode, apiV3FormValidator, async(req, res) => {
     const { flag } = req.body;