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:
@@ -89,7 +92,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 +113,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 +135,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 +156,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 +177,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 +198,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

spec/file_translation/fts_common.yaml

@@ -114,7 +114,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error400Response'
+            $ref: '../api_common.yaml#/components/schemas/Error400Response'
           examples:
             response:
               value:

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,11 +25,12 @@ 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:
@@ -44,12 +43,12 @@ x-paths:
                         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