Просмотр исходного кода

support(jsdoc): add swagger document to import.js

Atsushi Nakatsugawa 1 год назад
Родитель
Сommit
f172e4799a
1 измененных файлов с 106 добавлено и 19 удалено
  1. 106 19
      apps/app/src/server/routes/apiv3/import.js

+ 106 - 19
apps/app/src/server/routes/apiv3/import.js

@@ -31,17 +31,13 @@ const router = express.Router();
  *            description: Import mode
  *            type: string
  *            enum: [insert, upsert, flushAndInsert]
- */
-
-/**
- * @swagger
- *
- *  components:
- *    schemas:
  *      ImportStatus:
  *        description: ImportStatus
  *        type: object
  *        properties:
+ *          isTheSameVersion:
+ *            type: boolean
+ *            description: whether the version of the uploaded data is the same as the current GROWI version
  *          zipFileStat:
  *            type: object
  *            description: the property object
@@ -53,6 +49,77 @@ const router = express.Router();
  *          isImporting:
  *            type: boolean
  *            description: whether the current importing job exists or not
+ *      FileImportResponse:
+ *        type: object
+ *        properties:
+ *          meta:
+ *            type: object
+ *            properties:
+ *              version:
+ *                type: string
+ *              url:
+ *                type: string
+ *              passwordSeed:
+ *                type: string
+ *              exportedAt:
+ *                type: string
+ *                format: date-time
+ *              envVars:
+ *                type: object
+ *                properties:
+ *                  ELASTICSEARCH_URI:
+ *                    type: string
+ *          fileName:
+ *            type: string
+ *          zipFilePath:
+ *            type: string
+ *          fileStat:
+ *            type: object
+ *            properties:
+ *              dev:
+ *                type: integer
+ *              mode:
+ *                type: integer
+ *              nlink:
+ *                type: integer
+ *              uid:
+ *                type: integer
+ *              gid:
+ *                type: integer
+ *              rdev:
+ *                type: integer
+ *              blksize:
+ *                type: integer
+ *              ino:
+ *                type: integer
+ *              size:
+ *                type: integer
+ *              blocks:
+ *                type: integer
+ *              atime:
+ *                type: string
+ *                format: date-time
+ *              mtime:
+ *                type: string
+ *                format: date-time
+ *              ctime:
+ *                type: string
+ *                format: date-time
+ *              birthtime:
+ *                type: string
+ *                format: date-time
+ *          innerFileStats:
+ *            type: array
+ *            items:
+ *              type: object
+ *              properties:
+ *                fileName:
+ *                  type: string
+ *                collectionName:
+ *                  type: string
+ *                size:
+ *                  type: integer
+ *                  nullable: true
  */
 /** @param {import('~/server/crowi').default} crowi Crowi instance */
 export default function route(crowi) {
@@ -101,6 +168,8 @@ export default function route(crowi) {
    *  /import:
    *    get:
    *      tags: [Import]
+   *      security:
+   *        - api_key: []
    *      operationId: getImportSettingsParams
    *      summary: /import
    *      description: Get import settings params
@@ -114,6 +183,19 @@ export default function route(crowi) {
    *                  importSettingsParams:
    *                    type: object
    *                    description: import settings params
+   *                    properties:
+   *                      esaTeamName:
+   *                        type: string
+   *                        description: the team name of esa.io
+   *                      esaAccessToken:
+   *                        type: string
+   *                        description: the access token of esa.io
+   *                      qiitaTeamName:
+   *                        type: string
+   *                        description: the team name of qiita.com
+   *                      qiitaAccessToken:
+   *                        type: string
+   *                        description: the access token of qiita.com
    */
   router.get('/', accessTokenParser, loginRequired, adminRequired, async(req, res) => {
     try {
@@ -138,6 +220,8 @@ export default function route(crowi) {
    *  /import/status:
    *    get:
    *      tags: [Import]
+   *      security:
+   *        - api_key: []
    *      operationId: getImportStatus
    *      summary: /import/status
    *      description: Get properties of stored zip files for import
@@ -167,6 +251,8 @@ export default function route(crowi) {
    *  /import:
    *    post:
    *      tags: [Import]
+   *      security:
+   *        - api_key: []
    *      operationId: executeImport
    *      summary: /import
    *      description: import a collection from a zipped json
@@ -297,27 +383,26 @@ export default function route(crowi) {
    *  /import/upload:
    *    post:
    *      tags: [Import]
+   *      security:
+   *        - api_key: []
    *      operationId: uploadImport
    *      summary: /import/upload
    *      description: upload a zip file
+   *      requestBody:
+   *        content:
+   *          multipart/form-data:
+   *            schema:
+   *              type: object
+   *              properties:
+   *                file:
+   *                  format: binary
    *      responses:
    *        200:
    *          description: the file is uploaded
    *          content:
    *            application/json:
    *              schema:
-   *                properties:
-   *                  meta:
-   *                    type: object
-   *                    description: the meta data of the uploaded file
-   *                  fileName:
-   *                    type: string
-   *                    description: the base name of the uploaded file
-   *                  fileStats:
-   *                    type: array
-   *                    items:
-   *                      type: object
-   *                      description: the property of each extracted file
+   *                $ref: '#/components/schemas/FileImportResponse'
    */
   router.post('/upload', accessTokenParser, loginRequired, adminRequired, uploads.single('file'), addActivity, async(req, res) => {
     const { file } = req;
@@ -354,6 +439,8 @@ export default function route(crowi) {
    *  /import/all:
    *    delete:
    *      tags: [Import]
+   *      security:
+   *        - api_key: []
    *      operationId: deleteImportAll
    *      summary: /import/all
    *      description: Delete all zip files