Tcm 5257 summarize issues with swagger api documentation for creating sdk

package.json

@@ -2,29 +2,27 @@
   "name": "smartling-openapi-spec",
   "version": "0.0.1",
   "dependencies": {
+    "@redocly/cli": "^1.25.4",
     "@stoplight/json-ref-resolver": "^3.1.3",
     "@stoplight/path": "^1.3.2",
+    "ansi-colors": "^4.1.1",
     "bower": "^1.8.8",
     "connect": "^3.7.0",
     "cors": "^2.8.5",
     "deploy-to-gh-pages": "^1.3.7",
+    "fancy-log": "^2.0.0",
     "gulp": "^4.0.2",
     "gulp-connect": "^5.7.0",
-    "ansi-colors": "^4.1.1",
-    "fancy-log": "^2.0.0",
     "js-yaml": "^4.1.0",
     "portfinder": "^1.0.28",
-    "resolve-swagger-refs": "^0.1.5",
-    "shelljs": "^0.8.5",
-    "swagger-repo": "^2.0.0-rc.15",
-    "swagger-ui": "^4.18.1"
+    "shelljs": "^0.8.5"
   },
   "private": true,
   "scripts": {
     "deploy": "npm run build && deploy-to-gh-pages --update web_deploy",
     "build": "node ./scripts/build.js",
     "swagger": "swagger-repo",
-    "test": "swagger-repo validate",
+    "test": "redocly lint ./spec/openapi.yaml --max-problems 5000",
     "start": "gulp serve",
     "process-yaml": "node ./spec/process-yaml.js",
     "deploy-branch": "node ./scripts/deploy-branch.js"

scripts/build.js

@@ -9,16 +9,6 @@ mkdir('-p', 'web_deploy');
 
 cp('-R', 'web/*', 'web_deploy/');
 
-exec('npm run swagger build  --        -o web_deploy');
-exec('npm run swagger bundle --        -o web_deploy/swagger.json');
-exec('npm run swagger bundle -- --yaml -o web_deploy/swagger.yaml');
-
-
-mkdir('-p', 'web_deploy/spec');
-cp('-R', 'spec/translation_quality', 'web_deploy/spec');
-cp('-R', 'spec/issues', 'web_deploy/spec');
-cp('-R', 'spec/job_batches_v1', 'web_deploy/spec');
-cp('-R', 'spec/job_batches_v2', 'web_deploy/spec');
-cp('-R', 'spec/file_translation', 'web_deploy/spec');
-cp('-R', 'spec/glossary_v3', 'web_deploy/spec');
-cp('-R', 'spec/api_common.yaml', 'web_deploy/spec');
+exec('redocly build-docs ./spec/openapi.yaml -o web_deploy/index.html');
+exec('redocly bundle ./spec/openapi.yaml     -o web_deploy/swagger.yaml');
+exec('redocly bundle ./spec/openapi.yaml     -o web_deploy/swagger.json');

scripts/deploy-branch.js

@@ -8,20 +8,12 @@ set('-v');
 
 var branch = process.env.BRANCH_NAME && process.env.BRANCH_NAME.toLowerCase();
 if (branch && branch !== 'gh-pages') {
-  var branchPath = path.join('.tmp', 'preview', branch, '/');
-  mkdir('-p', branchPath);
-  cp('-R', 'web/*', branchPath);
-  exec('npm run swagger bundle -- -o ' + branchPath + 'swagger.json');
+    var branchPath = path.join('.tmp', 'preview', branch, '/');
+    mkdir('-p', branchPath);
+    cp('-R', 'web/*', branchPath);
+    exec('redocly build-docs ./spec/openapi.yaml -o ' + branchPath + 'index.html');
+    exec('redocly bundle ./spec/openapi.yaml     -o ' + branchPath + 'swagger.yaml');
+    exec('redocly bundle ./spec/openapi.yaml     -o ' + branchPath + 'swagger.json');
 
-  var specFolder = path.join(branchPath, 'spec');
-  mkdir('-p', specFolder);
-  cp('-R', 'spec/translation_quality', specFolder);
-  cp('-R', 'spec/file_translation', specFolder);
-  cp('-R', 'spec/issues', specFolder);
-  cp('-R', 'spec/job_batches_v1', specFolder);
-  cp('-R', 'spec/job_batches_v2', specFolder);
-  cp('-R', 'spec/glossary_v3', specFolder);
-  cp('-R', 'spec/api_common.yaml', specFolder);
-
-  exec('deploy-to-gh-pages --update .tmp');
+    exec('deploy-to-gh-pages --update .tmp');
 }

spec/api_common.yaml

@@ -3,22 +3,25 @@ components:
       accountUid:
         name: accountUid
         in: path
-        type: string
+        schema:
+          type: string
         required: true
         description: The account’s unique identifier. This can be found in the Smartling Dashboard under Account Settings > API.
 
       projectId:
         name: projectId
         in: path
         required: true
-        type: string
+        schema:
+          type: string
         description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
 
       localeId:
         name: localeId
         in: path
         required: true
-        type: string
+        schema:
+          type: string
         description: A valid Smartling Locale ID.
 
   requestBodies:
@@ -50,6 +53,7 @@ components:
           type: string
           enum:
             - SUCCESS
+            - ACCEPTED
           description: Indicates whether the response was successful or what error has occurred.
 
     EmptyResponse:
@@ -66,6 +70,22 @@ components:
                   type: object
               type: object
 
+    NotEmptyResponse:
+      type: object
+      required:
+        - response
+      properties:
+        response:
+          allOf:
+            - $ref: '#/components/schemas/SuccessResponse'
+            - properties:
+                data:
+                  properties:
+                    message:
+                      type: string
+                  type: object
+              type: object
+
     Error:
       type: object
       properties:
@@ -89,7 +109,7 @@ components:
           properties:
             code:
               description: >-
-                Indicates whether the response was successful or what error has occured.
+                Indicates whether the response was successful or what error has occurred.
               enum:
                 - VALIDATION_ERROR
               type: string
@@ -110,7 +130,7 @@ components:
           properties:
             code:
               description: >-
-                Indicates whether the response was successful or what error has occured.
+                Indicates whether the response was successful or what error has occurred.
               enum:
                 - AUTHENTICATION_ERROR
                 - AUTHORIZATION_ERROR
@@ -132,7 +152,7 @@ components:
           properties:
             code:
               description: >-
-                Indicates whether the response was successful or what error has occured.
+                Indicates whether the response was successful or what error has occurred.
               enum:
                 - NOT_FOUND_ERROR
               type: string
@@ -153,7 +173,7 @@ components:
           properties:
             code:
               description: >-
-                Indicates whether the response was successful or what error has occured.
+                Indicates whether the response was successful or what error has occurred.
               enum:
                 - RESOURCE_LOCKED
               type: string
@@ -174,7 +194,7 @@ components:
           properties:
             code:
               description: >-
-                Indicates whether the response was successful or what error has occured.
+                Indicates whether the response was successful or what error has occurred.
               enum:
                 - MAX_OPERATIONS_LIMIT_EXCEEDED
               type: string
@@ -195,7 +215,7 @@ components:
           properties:
             code:
               description: >-
-                Indicates whether the response was successful or what error has occured.
+                Indicates whether the response was successful or what error has occurred.
               enum:
                 - GENERAL_ERROR
                 - MAINTENANCE_MODE_ERROR
@@ -224,12 +244,12 @@ components:
                 response:
                   code: VALIDATION_ERROR
                   errors:
-                    key: unknown.field
-                    message: >-
-                      The field unknown.parameter was not expected. Please
-                      consult the documentation to verify the fields you are
-                      submitting.
-                    details: unknown.parameter
+                    - key: unknown.field
+                      message: >-
+                        The field unknown.parameter was not expected. Please
+                        consult the documentation to verify the fields you are
+                        submitting.
+                      details: {}
 
     Error401ResponseDefinition:
       description: Provided credentials are not valid.
@@ -243,9 +263,9 @@ components:
                 response:
                   code: AUTHENTICATION_ERROR
                   errors:
-                    details: {}
-                    key: invalid_token
-                    message: Invalid token
+                    - key: invalid_token
+                      details: {}
+                      message: Invalid token
 
     Error429ResponseDefinition:
       description: Too many simultaneous API requests.
@@ -259,10 +279,10 @@ components:
                 response:
                   code: MAX_OPERATIONS_LIMIT_EXCEEDED
                   errors:
-                    key: too.many.requests
-                    message: >-
-                      The limit of 10 concurrent Smartling file API
-                      operations for this project has been exceeded.
+                    - key: too.many.requests
+                      message: >-
+                        The limit of 10 concurrent Smartling file API
+                        operations for this project has been exceeded.
 
     Error500ResponseDefinition:
       description: Unexpected error

spec/file_translation/fts_common.yaml

@@ -92,6 +92,7 @@ components:
         - response
     Error:
       type: object
+      nullable: true
       properties:
         key:
           description: Error key
@@ -114,15 +115,15 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error400Response'
+            $ref: '../api_common.yaml#/components/schemas/Error400Response'
           examples:
             response:
               value:
                 response:
                   code: VALIDATION_ERROR
                   errors:
-                    key: not.found
-                    message: >-
-                      mtUid jtcorrr3 not found
-                    details:
-                      mtUid: jtcorrr3
+                    - key: not.found
+                      message: >-
+                        mtUid jtcorrr3 not found
+                      details:
+                        mtUid: jtcorrr3

spec/file_translation/fts_language_detection.yaml

@@ -8,13 +8,11 @@ x-paths:
       tags:
         - File Machine Translations (MT)
       operationId: detectFileSourceLanguage
-      produces:
-        - application/json
       parameters:
         - $ref: './fts_common.yaml#/components/parameters/accountUidPathParameter'
         - $ref: './fts_common.yaml#/components/parameters/fileUidPathParameter'
       responses:
-        '202':
+        202:
           content:
             application/json:
               examples:
@@ -27,29 +25,30 @@ x-paths:
               schema:
                 $ref: '#/components/schemas/LanguageDetectionResponse'
           description: OK
-        '400':
+        400:
+          description: "Validation error"
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error400Response'
+                $ref: '../api_common.yaml#/components/schemas/Error400Response'
               examples:
                 response:
                   value:
                     response:
                       code: VALIDATION_ERROR
                       errors:
-                        key: not.found
-                        message: >-
-                          fileUid h5dhjbg1ganp not found
-                        details:
-                          field: "fileUid"
+                        - key: not.found
+                          message: >-
+                            fileUid h5dhjbg1ganp not found
+                          details:
+                            field: "fileUid"
 
-        '401':
-          $ref: '#/components/responses/Error401ResponseDefinition'
-        '429':
-          $ref: '#/components/responses/Error429ResponseDefinition'
-        '500':
-          $ref: '#/components/responses/Error500ResponseDefinition'
+        401:
+          $ref: '../api_common.yaml#/components/responses/Error401ResponseDefinition'
+        429:
+          $ref: '../api_common.yaml#/components/responses/Error429ResponseDefinition'
+        500:
+          $ref: '../api_common.yaml#/components/responses/Error500ResponseDefinition'
       x-code-samples:
         - lang: curl
           source: >
@@ -65,14 +64,12 @@ x-paths:
       tags:
         - File Machine Translations (MT)
       operationId: getLanguageDetectionStatus
-      produces:
-        - application/json
       parameters:
         - $ref: './fts_common.yaml#/components/parameters/accountUidPathParameter'
         - $ref: './fts_common.yaml#/components/parameters/fileUidPathParameter'
         - $ref: './fts_common.yaml#/components/parameters/languageDetectionUidPathParameter'
       responses:
-        '200':
+        200:
           content:
             application/json:
               examples:
@@ -91,14 +88,14 @@ x-paths:
               schema:
                 $ref: '#/components/schemas/LanguageDetectionStatusResponse'
           description: OK
-        '400':
+        400:
           $ref: './fts_common.yaml#/components/responses/Error400ResponseDefinition'
-        '401':
-          $ref: '#/components/responses/Error401ResponseDefinition'
-        '429':
-          $ref: '#/components/responses/Error429ResponseDefinition'
-        '500':
-          $ref: '#/components/responses/Error500ResponseDefinition'
+        401:
+          $ref: '../api_common.yaml#/components/responses/Error401ResponseDefinition'
+        429:
+          $ref: '../api_common.yaml#/components/responses/Error429ResponseDefinition'
+        500:
+          $ref: '../api_common.yaml#/components/responses/Error500ResponseDefinition'
       x-code-samples:
         - lang: curl
           source: >
@@ -143,12 +140,13 @@ components:
                       type: array
                       items:
                         type: object
-                      languageId:
-                        type: string
-                        description: Detected source language of the file
-                      defaultLocaleId:
-                        type: string
-                        description: Smartling's default locale that corresponds to languageId
+                        properties:
+                          languageId:
+                            type: string
+                            description: Detected source language of the file
+                          defaultLocaleId:
+                            type: string
+                            description: Smartling's default locale that corresponds to languageId
                   type: object
 
               type: object