apib2swagger 1.10.0 → 1.14.0

package/src/parameters.js

@@ -0,0 +1,111 @@
+
+const getParamType = (name, uriTemplate, options) => {
+    const defaultType = options.openApi3 ? 'query' : 'body'
+    if (!uriTemplate) return defaultType;
+    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 defaultType;
+}
+
+module.exports.processParameters = (parameters, uriTemplate, options) => {
+    const { openApi3 } = options
+    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, options),
+            'description': parameter.description
+        };
+        if (openApi3) {
+            if (parameter.required) {
+                // Only add required if the value is true. False is not an accepted value.
+                param.required = true
+          
+            }
+        } else {
+            param.required = parameter.required
+        }
+        if (parameter.example) {
+            if (openApi3) {
+                param.example = parameter.example
+            } else {
+                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 {
+            if (openApi3) {
+                param.schema = { type: paramType }
+                if (parameterDefault) {
+                    param.schema.default = parameterDefault;
+                }
+                if (allowedValues.length > 0) {
+                    param.schema.enum = allowedValues;
+                }
+            } else {
+                param.type = paramType;
+                if (parameterDefault) {
+                    param.default = parameterDefault;
+                }
+                if (allowedValues.length > 0) {
+                    param.enum = allowedValues;
+                }
+            }
+        }
+        params.push(param);
+    }
+    return params;
+}
+

package/src/requests.js

@@ -0,0 +1,344 @@
+const { hasFileRef, getRefFromInclude, searchDataStructure, generateSchemaFromExample } = require('./util')
+const isEqual = require('lodash.isequal')
+const escapeJSONPointer = require('./escape_json_pointer')
+
+const swaggerHeaders = function (options, headers) {
+    var params = [];
+    const skipParams = options.openApi3 ? ['content-type'] : ['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
+        };
+        if (options.openApi3) {
+            param.schema = { type: 'string' }
+            param.example = element.value
+        } else {
+            param['x-example'] = element.value
+            param.type = 'string' // TODO: string, number, boolean, integer, array
+        }
+        if (!params.find(p => isEqual(p, param)))
+        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;
+}
+
+const setSecurity = (context, request, operation) => {
+    if (context.options.openApi3){
+        return operation
+    }
+    var security = swaggerSecurity(context, request.headers);
+    if (security) {
+        if (!operation.security) {
+            operation.security = [security];
+        } else {
+            if (!operation.security.find(s => isEqual(s, security))){
+                operation.security.push(security);
+            }
+        }
+    }
+    return operation
+}
+
+const setSwaggerRequestSchema = (operation, schema) => {
+    if (!schema.length) {
+        return operation
+    }
+    if (schema.length === 1) {
+        operation.parameters.push({ name: 'body', in: 'body', schema: schema[0].scheme })
+        return operation
+    } 
+    operation.parameters.push({ 
+        name: 'body', 
+        in: 'body', 
+        schema: { 
+            anyOf: schema.map((s) => s.scheme)
+        } 
+    });
+    return operation
+}
+
+const mergeHeaders = (headers, parameters, options) => {
+    const existingHeaders = parameters
+        .filter(param => param.in === 'header')
+        .map(param => param.name.toLowerCase());
+    
+    let nonDuplicateHeaders
+    if (options.openApi3) {
+        // We are comparing the whole object instead of just the name to allow duplicate names.
+        // In doing so, we allow multiple types of Authorization headers to be specified.
+        nonDuplicateHeaders = headers.filter(header => 
+            !parameters.find(p => isEqual(p, header))
+        )
+    } else {
+        nonDuplicateHeaders = headers.filter(header => 
+            !existingHeaders.includes(header.name.toLowerCase())
+        );
+    }
+    return parameters.concat(nonDuplicateHeaders);
+}
+
+const processRequestSchema = (request, options) => {
+    let schema
+    const { openApi3 } = options
+    if (openApi3 && hasFileRef(request.schema)) {
+        return getRefFromInclude(request.schema)
+    }
+
+    // referencing Model's Schema is also here (no need to reference definitions)
+    try {
+        schema = JSON.parse(request.schema);
+        delete schema['$schema'];
+    } catch (e){
+        // If we can't parse the request schema we have nothing left to do here. 
+        return
+    }
+    try {
+        // if we have example values in the body then insert them into the json schema
+        if (!openApi3) {
+            var body = JSON.parse(request.body);
+
+            if (schema['type'] === 'object') {
+                schema.example = body;
+            } else if (schema['type'] === 'array') {
+                schema.items.example = body;
+            }
+        }
+    // Catch any error from parsing the request body. However, if there is an error 
+    // (ex. no request body given), we still want to keep the schema.
+    } catch (e) {}
+    return schema
+}
+
+const processRequestAttributes = (request, options, contentType) => {
+    const schema = []
+    const scheme = searchDataStructure(request.content, options); // Attributes 4
+    if (scheme) schema.push({ scheme, contentType });
+    if (request.reference) {
+        const componentsPath = options.openApi3 ? '#/components/schemas' : '#/definitions/'
+        schema.push({ 
+            scheme: { 
+                '$ref': componentsPath + escapeJSONPointer(request.reference.id + 'Model') 
+            }, 
+            contentType 
+        });
+    }
+    return schema
+}
+const buildBodyExamples = (requestBody, bodyExamples, contentType) => {
+    let body
+    if (typeof requestBody === 'string') {
+        if (hasFileRef(requestBody)){
+            body = getRefFromInclude(requestBody)
+        } else {
+            try {
+                body = JSON.parse(requestBody);
+            } catch (e) {
+                if (contentType === 'text/plain') {
+                    body = requestBody 
+                }
+            }
+        }
+    }
+
+    if (typeof body !== 'object' && typeof body !== 'array' && typeof body !== 'string') {
+        return bodyExamples
+    }
+
+    if (!bodyExamples[contentType]) {
+        bodyExamples[contentType] = { example: body }
+    } else if (bodyExamples[contentType].examples) {
+        const count = Object.keys(bodyExamples[contentType].examples).length + 1
+        const name = 'example' + count
+        bodyExamples[contentType].examples[name] = body.$ref ? body : { value: body }
+    } else {
+        const existingExample = bodyExamples[contentType].example
+        bodyExamples[contentType].examples = {
+            example1: existingExample.$ref ? existingExample : { value: existingExample },
+            example2: body.$ref ? body : { value: body }
+        }
+        delete bodyExamples[contentType].example
+    }
+    return bodyExamples
+}
+
+const getOpenApiRequestSchema = (request, schema, contentType, options) => {
+    /* 
+        With OpenAPI3 we can make full use of Attributes because examples no longer live
+        on the schema object and therefore, we don't lose our examples when we use 
+        Attributes as the schema definition.
+    */
+    const contentTypeScheme = {}
+    if (!options.preferReference) {
+        if (request.schema) { // Schema section in Request section
+            contentTypeScheme[contentType] = processRequestSchema(request, options)
+        } 
+        if (contentTypeScheme[contentType]) {
+            schema.push({ scheme: contentTypeScheme[contentType], contentType });
+        } else {
+            const attributes = processRequestAttributes(request, options, contentType) 
+            schema.push(...attributes)
+        }
+    } else {
+        const attributes = processRequestAttributes(request, options, contentType) 
+        if (attributes.length) {
+            schema.push(...attributes)
+        } else {
+            contentTypeScheme[contentType] = processRequestSchema(request, options)
+            if (contentTypeScheme[contentType]) {
+                schema.push({ scheme: contentTypeScheme[contentType], contentType });
+            }
+        }
+    }
+    // If there are no schema but we have a body example, try to generate a schema from it.
+    // We stop at 1 auto-generated schema.
+    if (request.body && schema.length === 0) {
+        contentTypeScheme[contentType] = generateSchemaFromExample(request.headers, request.body, options);
+        if (contentTypeScheme[contentType]){
+            schema.push({ scheme: contentTypeScheme[contentType], contentType });
+        }
+    }
+    return schema
+}
+
+const setOpenApiRequestSchema = (operation, schema) => {
+    if (!schema.length){
+        return operation
+    }
+
+    // Make sure all content types exist to make setting the schemes easier.
+    schema.forEach(s => {
+        if (!operation.requestBody.content[s.contentType]) {
+            operation.requestBody.content[s.contentType] = {}
+        }
+    })
+
+    if (schema.length === 1) {
+        if (!operation.requestBody.content[schema[0].contentType]){
+            operation.requestBody.content[schema[0].contentType] = schema[0].scheme 
+        } else {
+            operation.requestBody.content[schema[0].contentType].schema = schema[0].scheme 
+        }
+        return operation
+    } 
+
+    schema.forEach(s => {
+        if (!operation.requestBody.content[s.contentType].schema){
+            operation.requestBody.content[s.contentType].schema = s.scheme
+            return
+        }   
+        // If a schema exist for this content type, 
+        // we need to use oneOf because we have an additional schema to add.
+        const { oneOf } = operation.requestBody.content[s.contentType].schema
+        if (oneOf){
+            // If oneOf already exists we can just add the new schema if its not a duplicate.
+            if (!oneOf.find(sc => isEqual(sc, s.scheme))){
+                operation.requestBody.content[s.contentType].schema.oneOf.push(s.scheme)
+            }
+            return
+        }
+        const existing = operation.requestBody.content[s.contentType].schema
+        if (isEqual(existing, s.scheme)){
+            return
+        }
+        // If oneOf does not exist and its not a duplicate, we need to create it, 
+        // making sure to include the existing schema.
+        operation.requestBody.content[s.contentType].schema = { 
+            oneOf: [
+                operation.requestBody.content[s.contentType].schema, // existing
+                s.scheme // additional
+            ]
+        }
+    })
+    return operation
+}
+
+module.exports.processRequests = (operation, action, context) => {
+    const { options } = context
+    const { openApi3 } = options
+    var schema = [],
+        scheme = searchDataStructure(action.content, options); // Attributes 3
+    if (scheme) schema.push({ contentType: 'application/json', scheme });
+
+    let bodyExamples = {}
+
+    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];
+            
+            operation = setSecurity(context, request, operation)
+
+            var headers = swaggerHeaders(options, request.headers);
+            if (headers) {
+                operation.parameters = mergeHeaders(headers, operation.parameters, options)
+            }
+         
+            const contentTypeHeader = request.headers.find((h) => h.name === 'Content-Type')
+            const contentType = contentTypeHeader ? contentTypeHeader.value : 'application/json'
+
+            if (request.body && openApi3) {
+                bodyExamples = buildBodyExamples(request.body, bodyExamples, contentType)
+            }
+
+            if (!openApi3) {
+                // Build schemas and examples for swagger 2.0
+                if (request.schema) {
+                    scheme = processRequestSchema(request, options)
+                    if (scheme) schema.push({ scheme, contentType });
+                } else {
+                    const attributes = processRequestAttributes(request, options, contentType) 
+                    schema.push(...attributes)
+                    // fall back to body
+                    if (request.body && schema.length === 0) {
+                        scheme = generateSchemaFromExample(request.headers, request.body, options);
+                        if (scheme) schema.push({ scheme, contentType });
+                    }
+                }
+            } else {
+                schema = getOpenApiRequestSchema(request, schema, contentType, options)
+            }
+        }
+    }
+    if (openApi3 && (schema.length || Object.keys(bodyExamples).length)){  
+        operation.requestBody = { content: {} }
+        if (Object.keys(bodyExamples).length) {
+            operation.requestBody.content = bodyExamples
+        }
+    }
+  
+    return openApi3 ? setOpenApiRequestSchema(operation, schema) : setSwaggerRequestSchema(operation, schema)
+}

package/src/responses.js

@@ -0,0 +1,181 @@
+const { fixArraySchema, hasFileRef, getRefFromInclude, searchDataStructure } = require('./util')
+const escapeJSONPointer = require('./escape_json_pointer')
+const isEqual = require('lodash.isequal')
+const http = require('http')
+
+const parseResponseSchema = (schema, options) => {
+    if (!schema) return
+    if (options.openApi3 && hasFileRef(schema)){
+        return getRefFromInclude(schema) 
+    }
+    try {
+        const result = JSON.parse(schema);
+        delete result['$schema'];
+        fixArraySchema(result); // work around for Swagger UI / Editor
+        return result
+    } catch (e) { }
+}
+
+const parseResponseBody = (body, header, options) => {
+    if (options.openApi3 && hasFileRef(body)){
+        return getRefFromInclude(body)
+    }
+    if (!header.value.match(/application\/.*json/)) {
+        return body
+    } 
+    try {
+        return JSON.parse(body);
+    } catch (e) { }
+}
+
+const getResponseSchema = (response, options) => {
+    const componentsPath = options.openApi3 ? '#/components/schemas' : '#/definitions/'
+    if (options.preferReference) { // MSON then schema
+        const inputSchema = searchDataStructure(response.content, options); // Attributes in response
+        if (inputSchema) {
+            return inputSchema
+        } else if (response.reference) {
+            return {
+                '$ref': componentsPath + escapeJSONPointer(response.reference.id + 'Model')
+            };
+        } else if (response.schema) {
+            return parseResponseSchema(response.schema, options)
+        }
+    } else { // schema then MSON
+        if (response.schema) {
+            const schema = parseResponseSchema(response.schema, options)
+            if (schema) {
+                return schema
+            }
+        }
+       
+        const inputSchema = searchDataStructure(response.content, options); // Attributes in response
+        if (inputSchema) return inputSchema;
+        if (response.reference) {
+            return {
+                '$ref': componentsPath + escapeJSONPointer(response.reference.id + 'Model')
+            };
+        }
+    }
+}
+
+const setResponseSchema = (responses, response, schema, options) => {
+    if (!options.openApi3){
+        responses[response.name].schema = schema
+        return responses
+    }
+    // In openAPI 3 the schema lives under the content type
+    const contentTypeHeader = response.headers.find((h) => h.name.toLowerCase() === 'content-type')
+    if (!contentTypeHeader.value) {
+        return responses
+    }
+    if (!responses[response.name].content[contentTypeHeader.value]){
+        responses[response.name].content[contentTypeHeader.value] = {}
+    }
+    
+    if (!responses[response.name].content[contentTypeHeader.value].schema){
+        responses[response.name].content[contentTypeHeader.value].schema = schema
+        return responses
+    }
+
+    // If a schema already exists, we need to use oneOf for additional unique schemas.
+    let existingSchema = { ...responses[response.name].content[contentTypeHeader.value].schema }
+    // It is possible that the given schema is a duplicate. If that's the case, we don't add it.
+    if (isEqual(existingSchema, schema)){
+        return responses
+    }
+
+    if (existingSchema.oneOf){
+        if (!existingSchema.oneOf.find((s) => isEqual(s, schema))){
+            responses[response.name].content[contentTypeHeader.value].schema.oneOf.push(schema)
+        }
+    } else {
+        responses[response.name].content[contentTypeHeader.value].schema = { oneOf: [existingSchema, schema] }
+    }
+    return responses
+}
+
+const setResponseExample = (responses, response, header, body, options) => {
+    if (!options.openApi3) {
+        // Sample path to Swagger 2.0 example:  
+        // responses -> 200 -> examples -> application/json -> { }
+        responses[response.name].examples[header.value] = body;
+        return responses
+    }
+    if (!body) {
+        return responses
+    }
+
+    // Sample path to OpenAPI 3.0 examples:  
+    // responses -> 200 -> content -> application/json -> example -> { }
+    // responses -> 200 -> content -> application/json -> examples -> example1 -> { }
+    const existingContainer = responses[response.name].content[header.value]
+    if (!existingContainer){
+        responses[response.name].content[header.value] = { example: body };
+    } else if (existingContainer.examples) {
+        const count = Object.keys(existingContainer.examples).length + 1
+        const exampleName = 'example' + count
+        responses[response.name].content[header.value].examples[exampleName] = body.$ref ? body : { value: body };
+    } else if (existingContainer.example) {
+        const existingExample = existingContainer.example
+        responses[response.name].content[header.value].examples = {
+            example1: existingExample.$ref ? existingExample : { value: existingExample },
+            example2: body.$ref ? body : { value: body }
+        }
+        delete responses[response.name].content[header.value].example
+    } else if (!existingContainer.example) {
+        responses[response.name].content[header.value].example = body
+    }
+    return responses
+}
+
+module.exports.processResponses = (examples, options) => {
+    let responses = {};
+    const { openApi3 } = options;
+    for (var l = 0; l < examples.length; l++) {
+        var example = examples[l];
+        for (var m = 0; m < example.responses.length; m++) {
+            var response = example.responses[m];
+
+            if (!responses[response.name]) {
+                responses[response.name] = { description: {}, headers: {} }
+            }
+           
+            responses[response.name].description = response.description || http.STATUS_CODES[response.name];
+            if (openApi3) {
+                // Does not overwrite and allows multiple examples.
+                if (!responses[response.name].content){
+                    responses[response.name].content = {};
+                }
+            } else {
+                // Overwrites every time
+                responses[response.name].examples = {}
+            }
+
+            const schema = getResponseSchema(response, options)
+
+            if (schema){
+                responses = setResponseSchema(responses, response, schema, options)
+            }
+            
+            for (var n = 0; n < response.headers.length; n++) {
+                var header = response.headers[n];
+                if (header.name.toLowerCase() === 'content-type') {
+                    let body = parseResponseBody(response.body, header, options)
+                    if (body || body === '') {
+                        responses = setResponseExample(responses, response, header, body, options) 
+                    }
+                } else if (header.name.toLowerCase() !== 'authorization') {
+                    if (openApi3) {
+                        responses[response.name].headers[header.name] = { 
+                            schema: { 'type': 'string' }
+                        }
+                    } else {
+                        responses[response.name].headers[header.name] = { 'type': 'string' }
+                    }
+                }
+            }
+        }
+    }
+    return responses;
+}