apib2swagger 1.12.0 → 1.13.0

package/index.js

@@ -1,36 +1,55 @@
 var url = require('url'),
-    http = require('http'),
     drafter = require('drafter.js'),
     UriTemplate = require('uritemplate'),
-    GenerateSchema = require('generate-schema');
+    jsonSchemaFromMSON = require('./src/mson_to_json_schema');
 
-var jsonSchemaFromMSON = require('./src/mson_to_json_schema'),
-    escapeJSONPointer = require('./src/escape_json_pointer');
+const { searchDataStructure, generateSchemaFromExample } = require('./src/util')
+const { processRequests } = require('./src/requests')
+const { processResponses } = require('./src/responses')
+const { processParameters } = require('./src/parameters')
 
 var apib2swagger = module.exports.convertParsed = function (apib, options) {
-    //console.log(JSON.stringify(apib, null, 4));
-    var swagger = {};
-    swagger.swagger = '2.0';
-    swagger.info = {
-        'title': apib.name,
-        'version': '',
+    const { openApi3, infoTitle } = options
+    var output = {};
+    if (openApi3) {
+        output.openapi = '3.0.3';
+    } else {
+        output.swagger = '2.0';
+    }
+    output.info = {
+        'title': infoTitle || apib.name,
+        'version': openApi3 ? '1.0.0' : '',
         'description': apib.description
     }
     apib.metadata.forEach(function (meta) {
-        //console.log(meta);
         if (meta.name.toLowerCase() === 'host') {
-            var urlParts = url.parse(meta.value);
-            swagger.host = urlParts.host;
-            swagger.basePath = urlParts.pathname;
-            swagger.schemes = [urlParts.protocol.replace(':', '')];
-        } else if (meta.name.toLowerCase() === 'version') {
-            swagger.info.version = meta.value;
+            if (openApi3) {
+                output.servers = [
+                    {
+                        url: meta.value
+                    }
+                ];
+            } else {
+                var urlParts = url.parse(meta.value);
+                output.host = urlParts.host;
+                output.basePath = urlParts.pathname;
+                output.schemes = [urlParts.protocol.replace(':', '')];
+            }
+        }
+        if (meta.name.toLowerCase() === 'version' && meta.value) {
+            output.info.version = meta.value
         }
     });
-    swagger.paths = {};
-    swagger.definitions = {};
-    swagger.securityDefinitions = {};
-    var converterContext = { swagger: swagger, options: options };
+    output.paths = {};
+
+    if (openApi3) {
+        output.components = { schemas: {} }
+    } else {
+        output.definitions = {}
+        output.securityDefinitions = {};
+    }
+
+    var converterContext = { swagger: output, options: options };
     var tags = {};
     apib.content.filter(function (content) {
         return content.element === 'category';
@@ -42,21 +61,32 @@ var apib2swagger = module.exports.convertParsed = function (apib, options) {
         category.content.forEach(function (content) {
             if (content.element === 'resource') {
                 // (name, description) in Resource section are discarded
-                swaggerDefinitions(swagger.definitions, content);
+                const definitions = swaggerDefinitions(content, options);
+                if (openApi3) {
+                    output.components.schemas = { ...output.components.schemas, ...definitions }
+                } else {
+                    output.definitions = { ...output.definitions, ...definitions }
+                }
                 swaggerPaths(converterContext, groupName, content);
             } else if (content.element === 'copy') {
                 // group description here
                 tags[groupName].description = content.content;
             } else if (content.element === 'dataStructure') {
-                swagger.definitions[content.content[0].meta.id] = jsonSchemaFromMSON(content);
+                const { id } = content.content[0].meta
+                const schema = jsonSchemaFromMSON(content, options);
+                if (openApi3) {
+                    output.components.schemas[id] = schema
+                } else {
+                    output.definitions[id] = schema
+                }
             }
         });
     });
-    swagger.tags = [];
+    output.tags = [];
     for (var key in tags) {
-        swagger.tags.push(tags[key]);
+        output.tags.push(tags[key]);
     }
-    return swagger;
+    return output;
 }
 
 function swaggerPathName(uriTemplate) {
@@ -73,29 +103,43 @@ function swaggerPathName(uriTemplate) {
     return decodeURIComponent(uriTemplate.expand(params));
 }
 
-var swaggerDefinitions = function (definitions, resource) {
+var swaggerDefinitions = function (resource, options) {
     var scheme;
+    const result = {}
+    const { openApi3 } = options
     if (resource.name) {
-        scheme = searchDataStructure(resource.content); // Attributes 1
-        definitions[resource.name] = scheme ? scheme : {};
+        scheme = searchDataStructure(resource.content, options); // Attributes 1
+        if (openApi3) {
+            if (scheme) {
+                result[resource.name] = scheme
+            }
+        } else {
+            result[resource.name] = scheme ? scheme : {};
+        }
     }
     const model = resource.model;
     if (model.content && model.name) {
-        scheme = searchDataStructure(model.content); // Attribute 2
+        scheme = searchDataStructure(model.content, options); // Attribute 2
         // fall back to body
         if (!scheme && model.content.length > 0) {
-            scheme = generateSchemaFromExample(model.headers, model.content[0].content);
+            scheme = generateSchemaFromExample(model.headers, model.content[0].content, options);
+        }
+        if (openApi3) {
+            if (scheme) {
+                result[model.name + 'Model'] = scheme
+            }
+        } else {
+            result[model.name + 'Model'] = scheme ? scheme : {};
         }
-        definitions[model.name + 'Model'] = scheme ? scheme : {};
     }
+    return result
 };
 
 var swaggerPaths = function (context, tag, resource) {
     var paths = context.swagger.paths;
     var uriTemplate = UriTemplate.parse(resource.uriTemplate),
         pathName = swaggerPathName(uriTemplate);
-    //path.parameters = swaggerParameters(resource.parameters, uriTemplate);
-    var pathParams = swaggerParameters(resource.parameters, uriTemplate); // for swagger ui
+    var pathParams = processParameters(resource.parameters, uriTemplate, context.options); // for swagger ui
     for (var k = 0; k < resource.actions.length; k++) {
         var action = resource.actions[k];
         if (!action.attributes.uriTemplate) {
@@ -112,12 +156,12 @@ var swaggerPaths = function (context, tag, resource) {
 
 var swaggerOperation = function (context, pathParams, uriTemplate, action, tag) {
     var operation = {
-        'responses': swaggerResponses(action.examples, context.options),
+        'responses': processResponses(action.examples, context.options),
         'summary': action.name,
         'operationId': action.name,
         'description': action.description,
         'tags': tag ? [tag] : [],
-        'parameters': pathParams.concat(swaggerParameters(action.parameters, uriTemplate))
+        'parameters': pathParams.concat(processParameters(action.parameters, uriTemplate, context.options))
     };
     var produces = {}, producesExist = false;
     for (var key in operation.responses) {
@@ -133,332 +177,7 @@ var swaggerOperation = function (context, pathParams, uriTemplate, action, tag)
             operation.produces.push(mime);
         }
     }
-    // body parameter (schema)
-    var schema = [],
-        scheme = searchDataStructure(action.content); // Attributes 3
-    if (scheme) schema.push(scheme);
-    for (var j = 0; j < action.examples.length; j++) {
-        var example = action.examples[j];
-        for (var l = 0; l < example.requests.length; l++) {
-            var request = example.requests[l];
-
-            // TODO should apply to Model Section?
-            var security = swaggerSecurity(context, request.headers);
-            if (security) {
-                if (!operation.security) {
-                    operation.security = [security];
-                } else {
-                    // TODO remove duplications
-                    operation.security.push(security);
-                }
-            }
-
-            var headers = swaggerHeaders(context, request.headers);
-            if (headers) {
-                const existingHeaders = operation.parameters
-                    .filter(param => param.in === 'header')
-                    .map(param => param.name.toLowerCase());
-                const nonDuplicateHeaders = headers.filter(header => !existingHeaders.includes(header.name.toLowerCase()));
-                operation.parameters = operation.parameters.concat(nonDuplicateHeaders);
-            }
-
-            if (request.schema) { // Schema section in Request section
-                try {
-                    // referencing Model's Schema is also here (no need to referencing defenitions)
-                    scheme = JSON.parse(request.schema);
-                    delete scheme['$schema'];
-
-                    // if we have example values in the body then insert them into the json schema
-                    var body = JSON.parse(request.body);
-                    if (scheme['type'] === 'object') {
-                        scheme.example = body;
-                    } else if (scheme['type'] === 'array') {
-                        scheme.items.example = body;
-                    }
-                    if (scheme) schema.push(scheme);
-                } catch (e) { }
-            } else {
-                scheme = searchDataStructure(request.content); // Attributes 4
-                if (scheme) schema.push(scheme);
-                if (request.reference) {
-                    schema.push({ '$ref': '#/definitions/' + escapeJSONPointer(request.reference.id + 'Model') });
-                }
-                // fall back to body
-                if (request.body && (schema == null || schema.length == 0)) {
-                    scheme = generateSchemaFromExample(request.headers, request.body);
-                    if (scheme) schema.push(scheme);
-                }
-            }
-        }
-    }
-    if (schema.length == 1) {
-        operation.parameters.push({ name: 'body', in: 'body', schema: schema[0] });
-    } else if (schema.length > 1) {
-        operation.parameters.push({ name: 'body', in: 'body', schema: { anyOf: schema } });
-    }
-    return operation;
-}
-
-var swaggerHeaders = function (context, headers) {
-    var params = [];
-    const skipParams = ['content-type', 'authorization']; // handled in another way
-    for (let i = 0; i < headers.length; i++) {
-        const element = headers[i];
-        if (skipParams.includes(element.name.toLowerCase())) continue;
-        var param = {
-            'name': element.name,
-            'in': 'header',
-            'description': `e.g. ${element.value}`,
-            'required': false,
-            'x-example': element.value,
-            'type': 'string' // TODO: string, number, boolean, integer, array
-        };
-        params.push(param);
-    }
-    return params;
-};
-
-// generate security and securityDefinitions from authorization headers
-function swaggerSecurity(context, headers) {
-    var security = null;
-    headers.filter(function (header) {
-        return header.name.toLowerCase() === 'authorization';
-    }).forEach(function (header) {
-        if (header.value.match(/^Basic /)) {
-            if (!security) security = {};
-            security['basic'] = [];
-            context.swagger.securityDefinitions['basic'] = { type: 'basic' };
-        } else if (header.value.match(/^Bearer /)) {
-            if (!security) security = {};
-            if (context.options.bearerAsApikey) {
-                security['bearer'] = [];
-                context.swagger.securityDefinitions['bearer'] = {
-                    type: 'apiKey', in: 'header', name: 'Authorization'
-                };
-            } else {
-                security['oauth2'] = [];
-                context.swagger.securityDefinitions['oauth2'] = {
-                    type: 'oauth2', flow: 'accessCode',
-                    authorizationUrl: '', tokenUrl: '', scopes: {}
-                };
-            }
-        }
-    });
-    return security;
-}
-
-function swaggerParameters(parameters, uriTemplate) {
-    var PARAM_TYPES = {
-        'string': 'string',
-        'number': 'number',
-        'integer': 'integer',
-        'boolean': 'boolean', 'bool': 'boolean',
-        'array': 'array',
-        'file': 'file'
-    }
-    var params = [];
-    //console.log(parameters);
-    for (var l = 0; l < parameters.length; l++) {
-        var parameter = parameters[l];
-        //console.log(parameter);
-        // in = ["query", "header", "path", "formData", "body"]
-        var param = {
-            'name': parameter.name,
-            'in': getParamType(parameter.name, uriTemplate),
-            'description': parameter.description,
-            'required': parameter.required
-        };
-
-        if (parameter.example) {
-            param['x-example'] = parameter.example
-        }
-
-        var paramType = undefined;
-        if (PARAM_TYPES.hasOwnProperty(parameter.type)) {
-            paramType = PARAM_TYPES[parameter.type];
-        } else {
-            paramType = 'string';
-        }
-
-        var allowedValues = []
-        for (var j = 0; j < parameter.values.length; j++) {
-            allowedValues.push(parameter.values[j].value);
-        }
-
-        var parameterDefault = undefined;
-        if (parameter.default) {
-            if (paramType === 'number' || paramType === 'integer') {
-                parameterDefault = Number(parameter.default);
-            } else {
-                parameterDefault = parameter.default;
-            }
-        }
-
-        // Body parameters has all info in schema
-        if (param.in === 'body') {
-            param.schema = {
-                'type': paramType
-            }
-            if (allowedValues.length > 0) {
-                param.schema.enum = allowedValues;
-            }
-            if (parameterDefault) {
-                param.schema.default = parameterDefault;
-            }
-        }
-        else {
-            param.type = paramType;
-            if (parameterDefault) {
-                param.default = parameterDefault;
-            }
-            if (allowedValues.length > 0) {
-                param.enum = allowedValues;
-            }
-        }
-        params.push(param);
-    }
-    return params;
-}
-
-var searchDataStructure = function (contents) {
-    for (var i = 0; i < contents.length; i++) {
-        var content = contents[i];
-        if (content.element !== "dataStructure") continue;
-        return jsonSchemaFromMSON(content);
-    }
-};
-
-function generateSchemaFromExample(headers, example) {
-    if (!headers || !headers.some(header => (
-        header.name === 'Content-Type' && header.value.match(/application\/.*json/)
-    ))) {
-        return null;
-    }
-    try {
-        const body = JSON.parse(example);
-        const scheme = GenerateSchema.json("", body);
-        if (!scheme) {
-            return null;
-        }
-        delete scheme.title;
-        delete scheme.$schema;
-        // if we have example values in the body then insert them into the json schema
-        if (scheme['type'] === 'object') {
-            scheme.example = body;
-        } else if (scheme['type'] === 'array') {
-            scheme.items.example = body;
-        }
-        return scheme;
-    } catch (e) {
-        return null;
-    }
-}
-
-function getParamType(name, uriTemplate) {
-    if (!uriTemplate) return 'body';
-    for (var i = 0; i < uriTemplate.expressions.length; i++) {
-        var exp = uriTemplate.expressions[i];
-        if (!exp.varspecs) continue;
-        for (var j = 0; j < exp.varspecs.length; j++) {
-            var spec = exp.varspecs[j];
-            if (spec.varname === name) {
-                return exp.operator.symbol === '?' ? 'query' : 'path';
-            }
-        }
-    }
-    return 'body'; // TODO: decide 'header', 'formData', 'body'
-}
-
-function fixArraySchema(schema) {
-    if (schema.type === 'array') {
-        if (!schema.hasOwnProperty('items')) schema.items = {};
-    } else if (schema.type === 'object') {
-        for (var k in schema.properties) fixArraySchema(schema.properties[k]);
-    }
-}
-
-function swaggerResponses(examples, options) {
-    var responses = {};
-    //console.log(examples);
-    for (var l = 0; l < examples.length; l++) {
-        var example = examples[l];
-        //console.log(example);
-        for (var m = 0; m < example.responses.length; m++) {
-            var response = example.responses[m];
-            //console.log(response);
-            var swaggerResponse = {
-                "description": response.description || http.STATUS_CODES[response.name],
-                "headers": {},
-                "examples": {}
-            };
-            if (options.preferReference) { // MSON then schema
-                var schema = searchDataStructure(response.content); // Attributes in response
-                if (schema) {
-                    swaggerResponse.schema = schema;
-                } else if (response.reference) {
-                    swaggerResponse.schema = {
-                        '$ref': '#/definitions/' + escapeJSONPointer(response.reference.id + 'Model')
-                    };
-                } else if (response.schema) {
-                    try {
-                        swaggerResponse.schema = JSON.parse(response.schema);
-                        delete swaggerResponse.schema['$schema'];
-                        fixArraySchema(swaggerResponse.schema); // work around for Swagger UI / Editor
-                    } catch (e) { }
-                }
-            } else { // schema then MSON
-                if (response.schema) {
-                    try {
-                        swaggerResponse.schema = JSON.parse(response.schema);
-                        delete swaggerResponse.schema['$schema'];
-                        fixArraySchema(swaggerResponse.schema); // work around for Swagger UI / Editor
-                    } catch (e) { }
-                }
-                if (!swaggerResponse.schema) {
-                    var schema = searchDataStructure(response.content); // Attributes in response
-                    if (schema) swaggerResponse.schema = schema;
-                }
-                if (!swaggerResponse.schema && response.reference) {
-                    swaggerResponse.schema = {
-                        '$ref': '#/definitions/' + escapeJSONPointer(response.reference.id + 'Model')
-                    };
-                }
-            }
-            if (!swaggerResponse.schema) {
-                // fall back to body
-                // if (response.body) {
-                //     schema = GenerateSchema.json("", JSON.parse(response.body));
-                //     if (schema) {
-                //         delete schema.title;
-                //         delete schema.$schema;
-                //         swaggerResponse.schema = schema;
-                //     }
-                // }
-
-                // use object
-                // if (response.body) {
-                //     swaggerResponse.schema = {type: "object"};
-                // }
-            }
-            for (var n = 0; n < response.headers.length; n++) {
-                var header = response.headers[n];
-                if (header.name.toLowerCase() === 'content-type') {
-                    if (header.value.match(/application\/.*json/)) {
-                        try {
-                            swaggerResponse.examples[header.value] = JSON.parse(response.body);
-                            //swaggerResponse.schema = {type: "object"};
-                        } catch (e) { }
-                        continue;
-                    }
-                    swaggerResponse.examples[header.value] = response.body;
-                } else if (header.name.toLowerCase() !== 'authorization') {
-                    swaggerResponse.headers[header.name] = { 'type': 'string' }
-                }
-            }
-            responses[response.name] = swaggerResponse;
-        }
-    }
-    return responses;
+    return processRequests(operation, action, context)
 }
 
 exports.noconvert = function (data, callback) {
@@ -477,10 +196,6 @@ exports.convert = function (data, options, callback) {
     }
     try {
         var result = drafter.parse(data, { type: 'ast' });
-        //for (var i = 0; i < result.warnings.length; i++) {
-        //    var warn = result.warnings[i];
-        //    console.log(warn);
-        //}
         var swagger = apib2swagger(result.ast, options);
         return callback(null, { swagger: swagger });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apib2swagger",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Convert API Blueprint to Swagger.",
   "bin": "./bin/apib2swagger.js",
   "scripts": {
@@ -21,14 +21,16 @@
     "drafter.js": "^2.6.2",
     "generate-schema": "^2.5.0",
     "js-yaml": "^3.13.1",
+    "lodash.isequal": "^4.5.0",
     "nopt": "^3.0.6",
     "uritemplate": "^0.3.4"
   },
   "devDependencies": {
-    "coveralls": "^3.0.11",
+    "coveralls": "^3.1.1",
     "cross-env": "^5.2.0",
     "mocha": "^5.2.0",
     "nyc": "^13.3.0",
+    "sinon": "^12.0.1",
     "tv4": "^1.2.7"
   }
-}
+}

package/src/mson_to_json_schema.js

@@ -1,9 +1,9 @@
 var escapeJSONPointer = require('./escape_json_pointer');
 
-function convertMsonToJsonSchema(content) {
+function convertMsonToJsonSchema(content, options) {
     // for apib._version = "4.0"
     var mson = content.content[0];
-    var schema = convert(mson);
+    var schema = convert(mson, options);
     if (schema.type === 'array') {
         var fixedType = false;
         if (mson.attributes && mson.attributes.typeAttributes) {
@@ -18,16 +18,18 @@ function convertMsonToJsonSchema(content) {
     return schema;
 }
 
-function convert(mson) {
+function convert(mson, options) {
+    const { openApi3 } = options
+    const componentsPath = openApi3 ? '#/components/schemas/' : '#/definitions/'
     // mson.element = "boolean", "string", "number", "array", "enum", "object", CustomType
     switch (mson.element) {
         case 'array':
             if (!mson.content || mson.content.length === 0) {
                 return { type: 'array', items: {} };
             } else if (mson.content.length === 1) {
-                return { type: 'array', items: convert(mson.content[0]) };
+                return { type: 'array', items: convert(mson.content[0], options) };
             } else if (mson.content.length > 1) {
-                return { type: 'array', items: { 'anyOf': mson.content.map(convert) } };
+                return { type: 'array', items: { 'anyOf': mson.content.map((m) => convert(m, options)) } };
             }
         case 'enum':
             return convertEnum(mson.content);
@@ -39,7 +41,7 @@ function convert(mson) {
             return { type: mson.element };
         default:
             if (!mson.content) {
-                return { '$ref': '#/definitions/' + escapeJSONPointer(mson.element) };
+                return { '$ref': componentsPath + escapeJSONPointer(mson.element) };
             }
             break;
     }
@@ -51,7 +53,7 @@ function convert(mson) {
     for (var j = 0; mson.content && j < mson.content.length; j++) {
         var member = mson.content[j];
         if (member.element !== "member") continue;
-        schema.properties[member.content.key.content] = convert(member.content.value);
+        schema.properties[member.content.key.content] = convert(member.content.value, options);
         if (member.meta && member.meta.description) {
             schema.properties[member.content.key.content].description = member.meta.description;
         }
@@ -66,8 +68,8 @@ function convert(mson) {
                         schema.required.push(member.content.key.content);
                         break;
                     case 'nullable':
-                    schema.properties[member.content.key.content].type = [schema.properties[member.content.key.content].type, 'null']
-                    break;
+                        schema.properties[member.content.key.content].type = [schema.properties[member.content.key.content].type, 'null']
+                        break;
                 }
             });
         }
@@ -82,7 +84,7 @@ function convert(mson) {
     }
 
     if (mson.element !== 'object') {
-        return { 'allOf': [{ '$ref': '#/definitions/' + escapeJSONPointer(mson.element) }, schema] };
+        return { 'allOf': [{ '$ref': componentsPath + escapeJSONPointer(mson.element) }, schema] };
     }
 
     return schema;