apib2swagger 1.10.0 → 1.14.0

package/src/util.js

@@ -0,0 +1,127 @@
+const jsonSchemaFromMSON = require('./mson_to_json_schema')
+const GenerateSchema = require('generate-schema')
+const path = require('path')
+const fs = require('fs')
+
+module.exports.hasFileRef = (section) => section
+    .replace(/\s+/g, '') // remove spaces
+    .includes('<!--include')
+
+/* 
+  Takes a string with many includes and normalizes all of the includes so that the contents
+  can be imported or references to files can be created properly.
+  Includes input formats
+     <!-- include: path/to/file -->
+     <!-- include(path/to/file) -->
+     <!-- include(path/to/file -->
+  Includes output format <!-- include(path/to/file) -->
+*/
+module.exports.normalizeIncludes = (str) => str
+    .split('<!-- include')
+    .map((s, i) => {
+        if (i === 0) {
+            return s;
+        }
+        let include = s
+            .substr(0, s.indexOf('-->')) 
+            .trim()
+      
+        if (include.slice(-1) === ')'){
+            include = include.substr(0, include.length - 1)
+        }
+        if (include.slice(0, 1) === '(' || include.slice(0, 1) === ':'){
+            include = include.substr(1, include.length)
+        }
+        const restOfStr = s.substr(s.indexOf('-->') + 3, s.length)         
+        return include.trim() + ') -->' + restOfStr
+    })
+    .join('<!-- include('); 
+
+// Return a reference object to the file path from the include statement.
+// Even though includes should now be normalized, this handles a scenario where they may not be.
+module.exports.getRefFromInclude = (include) => {
+    let path = include.replace(/\s+/g, '') 
+    if (path.includes('include(') && path.includes('-->')) {
+        path = path.substring(
+            path.indexOf('(') + 1,
+            path.indexOf('-->')
+        )
+        // the closing paren is optional so we remove it if it is there.
+        const lastChar = path.slice(-1)
+        if (lastChar === ')'){
+            path = path.substring(0, path.length - 1)
+        }
+    } else if (path.includes('include:') && path.includes('-->')) {
+        path = path.substring(
+            path.indexOf(':') + 1,
+            path.indexOf('-->')
+        )
+    } else {
+        throw Error('Invalid include syntax:' + include)
+    }
+
+    return { $ref: path }
+}
+
+module.exports.searchDataStructure = function (contents, options) {
+    for (var i = 0; i < contents.length; i++) {
+        var content = contents[i];
+        if (content.element !== "dataStructure") continue;
+        return jsonSchemaFromMSON(content, options);
+    }
+};
+
+module.exports.generateSchemaFromExample = function (headers, example, options) {
+    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 (!options.openApi3) {
+            if (scheme['type'] === 'object') {
+                scheme.example = body;
+            } else if (scheme['type'] === 'array') {
+                scheme.items.example = body;
+            }
+        }
+        return scheme;
+    } catch (e) {
+        return null;
+    }
+}
+
+const fixArraySchema = function (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]);
+    }
+}
+module.exports.fixArraySchema = fixArraySchema
+
+module.exports.getAbsolutePath = function (options, filePath) {
+    const sd = options['source-dir']
+    const directory = sd ? path.normalize(sd) : null
+    let absolutePath 
+    if (directory) {
+        absolutePath = path.join(directory, filePath) // Try given (source-dir) directory
+        if (fs.existsSync(absolutePath)) return absolutePath
+    }
+    
+    absolutePath = path.join(process.cwd(), filePath) // Try execution location's directory
+    if (fs.existsSync(absolutePath)) return absolutePath
+    
+    absolutePath = path.join(path.dirname(options.input || ''), filePath) // Try input file's directory
+    if (fs.existsSync(absolutePath)) return absolutePath
+
+    return null
+}

package/test/input/Issue-#49.md

@@ -0,0 +1,24 @@
+# Group Users
+
+## A user [/user]
+
+### Get one user [GET]
++ Response 200 (application/json)
+  + Attributes (User)
++ Response 500 (application/json)
+
+## Some users [/users]
+
+### Get a collection of users [GET]
++ Response 200 (application/json)
+  + Attributes (array[User])
++ Response 500 (application/json)
+
+# Data Structures
+
+## User (object)
++ id (string, required)
++ name (string, nullable, required)
+
+## Users (object)
++ `users`(array[User], nullable, required)

package/test/input/OpenAPI3_attributes.md

@@ -0,0 +1,36 @@
+HOST: https://www.testhost.com
+
+# Some resource [GET /object]
++ Request (application/json)
+
++ Response 200 (application/json)
+    + Attributes (object)
+        + message (string)
+
++ Response 200 (application/json)
+    + Attributes (OtherMessage)
+
+# Some resource [POST /array/object]
++ Request (application/json)
+    + Attributes (Message)
+
++ Response 200 (application/json) 
+    + Attributes (array, fixed-type)
+        + (object)
+            + path: `/files` (required)
+            + otherMessage (OtherMessage)
+        
+# Some resource [GET /messages]
++ Request (application/json)
+
++ Response 200 (application/json)
+    + Attributes (array[Message], fixed-type)
+
+## Data structures
+
+# Message
+- message (string)
+
+# OtherMessage
+- otherMessage (string)
+- someNum (number)

package/test/input/OpenAPI3_headers.md

@@ -0,0 +1,74 @@
+HOST: https://www.testhost.com
+
+# Some resource [POST /some/resource]
++ Request (application/json)
+    + Header
+        x-testhost-auth-sign: signed body
+
+    + Header
+        Authorization: Bearer Admin
+    
+    + Header
+        Authorization: Bearer User
+    
+     + Schema
+        {
+            "type": "object",
+            "properties": {
+                "someType": {
+                    "type": "string"
+                }
+            }
+        }
+
++ Request (application/json)
+    + Header
+        x-testhost-auth-sign: signed body
+
+    + Header
+        Authorization: Bearer Admin
+    
+    + Header
+        Authorization: Bearer User
+
+   + Schema
+        {
+            "type": "object",
+            "properties": {
+                "someType": {
+                    "type": "string"
+                }
+            }
+        }
+
++ Response 200
+
+
+# Restricted resource [GET /some/restricted/resource]
+Has a duplicate header within a single declaration
++ Request (application/json)
+    + Header
+        Authorization: Bearer Admin
+        Authorization: Bearer Admin
+
+    + Schema
+        {
+            "type": "object",
+            "properties": {
+                "message1": {
+                    "type": "string",
+                    "description": "This is the message description "
+                }
+            }
+        }
+
++ Response 200
+
+# Additional resource [GET /additional/resource]
++ Request (application/json)
+    + Header
+        x-testhost-auth-sign: signed body
+        Authorization: Bearer Admin
+        Authorization: Bearer User
+
++ Response 200

package/test/input/OpenAPI3_includes.md

@@ -0,0 +1,22 @@
+HOST: https://www.testhost.com
+
+# Some resource [GET /some/resource]
++ Request (application/json)
+    + Body
+        <!-- include(./includes/resource-request-body.json) --> 
+    + Schema
+        <!-- include(./includes/resource-request-schema.json --> 
+
++ Request (application/json)
+    + Body
+        <!-- include(./includes/resource-request-body-2.json) --> 
+
++ Response 200 (application/json)
+    + Body
+        <!-- include: ./includes/resource-response-body.json -->  
+    + Schema
+        <!-- include: ./includes/resource-response-schema.json --> 
+
++ Response 200 (application/json)
+    + Body
+        <!-- include ( ./includes/resource-response-body-2.json -->  

package/test/input/OpenAPI3_requests.md

@@ -0,0 +1,162 @@
+HOST: https://www.testhost.com
+
+# Some resource [GET /some/resource/{pathParam}{?queryParam}]
++ Parameters
+    + pathParam: exampleValue (required, string)
+        + Default: defaultValue
+    + queryParam: value1 (required, enum[string])
+        + Members
+            + value1
+            + value2
+    + additionalQueryParam (string)
+
++ Request (application/json)
+    + Schema
+        {
+            "type": "object",
+            "properties": {
+                "message1": {
+                    "type": "string",
+                    "description": "This is the message description "
+                }
+            }
+        }
+
++ Request
+    + Schema
+        {
+            "type": "object",
+            "properties": {
+                "message2": {
+                    "type": "string",
+                    "description": "This is the message description "
+                }
+            }
+        }
+
++ Request
+    + Schema
+        {
+            "type": "object",
+            "properties": {
+                "message3": {
+                    "type": "string",
+                    "description": "This is the message description "
+                }
+            }
+        }
+
++ Request
+    duplicate
+    + Schema
+        {
+            "type": "object",
+            "properties": {
+                "message1": {
+                    "type": "string",
+                    "description": "This is the message description "
+                }
+            }
+        }
+
++ Response 200 (application/json)
+
+# Another resource [GET /another/resource/]
++ Request (application/json)
+    + Schema
+        {
+            "type": "object",
+            "properties": {
+                "message1": {
+                    "type": "string",
+                    "description": "This is the message description "
+                }
+            }
+        }
+
+    + Body
+        {
+            "message1": "Hello world"
+        }
+
++ Request (application/json)
+    + Schema
+        {
+            "type": "object",
+            "properties": {
+                "message2": {
+                    "type": "string",
+                    "description": "This is the message description "
+                }
+            }
+        }
+
+    + Body
+        {
+            "message2": "Hello world"
+        }
+
++ Response 200 (application/json)
+
+# Some resource [GET /withAttributes]
++ Request (application/json)
+    + Schema
+        {
+            "type": "object",
+            "properties": {
+                "someType": {
+                    "type": "string",
+                    "description": "This is the message description "
+                }
+            }
+        }
+    
++ Request (application/json)
+    + Attributes (Message)
+
++ Response 200 (application/json) 
+
+# Some resource [GET /onlyAttributes]
++ Attributes (Message)
+
++ Response 200 (application/json)
+
+
+# Some resource [GET /onlyExamples]
++ Request (application/json)
+    + Body
+    {
+        "message": "test1"
+    }
+
++ Request (application/json)
+    + Body
+    {
+        "message": "test2"
+    }
+
++ Request (application/json)
+    + Body
+    {
+        "message": "test3"
+    }
+
++ Request (text/plain)
+    + Body
+        test
+
++ Response 200 (application/json)
+
+# Some resource [GET /bodyOnly]
++ Request (application/json)
+    + Body
+    {
+        "message": "test2"
+    }
+
++ Response 200 (application/json)
+
+## Data structures
+
+# Message
+- message (string)

package/test/input/OpenAPI3_responses.md

@@ -0,0 +1,177 @@
+HOST: https://www.testhost.com
+
+# Some resource [GET /some/resource]
+
++ Request
+
++ Response 200 (application/json)
+    + Headers
+        X-My-Message-Header: 42
+
+    + Body
+        { 
+            "message": "Hello World!" 
+        }
+
+    + Schema
+        {
+            "type": "object",
+            "properties": {
+                "message": {
+                    "type": "string",
+                    "description": "This is the message description "
+                }
+            }
+        }
+
+
++ Response 200 (application/json)
+    Unique schema
+
+    + Headers
+        X-My-Message-Header: 42
+
+    + Body
+        { "other": "Hello World!" }
+
+    + Schema
+        {
+            "type": "object",
+            "properties": {
+                "other": {
+                    "type": "string",
+                    "description": "This is the message description "
+                }
+            }
+        }
+
++ Response 200 (application/json)
+    Duplicate Schema
+
+    + Headers
+        X-My-Message-Header: 42
+
+    + Body
+        { "other": "Hello World!" }
+
+    + Schema
+        {
+            "type": "object",
+            "properties": {
+                "message": {
+                    "type": "string",
+                    "description": "This is the message description "
+                }
+            }
+        }
+
++ Response 200 (application/json)
+    Array schema
+
+      + Headers
+        X-My-Message-Header: 42
+
+    + Body
+        [{ "message": "Hello World!" }]
+
+    + Schema
+        {
+            "type": "array",
+            "items":  {
+                "type": "object",
+                "properties": {
+                    "message": {
+                        "type": "string",
+                        "description": "This is the message description "
+                    }
+                }
+            }
+        }
+
+
++ Response 400 (application/json)
+    + Body
+        { "message": "Invalid data" }
+
+# Some resource [POST /some/resource]
+
++ Request
+
++ Response 200 (application/json)
+    + Headers
+        X-My-Message-Header: 42
+
+    + Body
+        { 
+            "message": "Hello World!" 
+        }
+
+    + Schema
+        {
+            "type": "object",
+            "properties": {
+                "message": {
+                    "type": "string",
+                    "description": "This is the message description "
+                }
+            }
+        }
+
+
++ Response 200 (application/json)
+    + Headers
+        X-My-Message-Header: 42
+
+    + Body
+        { "message": "Hello World!" }
+
+    + Schema
+        {
+            "type": "object",
+            "properties": {
+                "message": {
+                    "type": "string",
+                    "description": "This is the message description "
+                }
+            }
+        }
+
+# Some resource [GET /test/attributes]
+
+- Request
+
+- Response 200 (application/json)
+    - Body
+        { "message": "Hello World!" }
+
+    - Attributes (Message)
+
+- Response 200 (application/json)
+    - Body
+        { "message": "Hello World2" }
+
+    - Attributes (Message)
+
+- Response 200 (application/json)
+    - Body
+        { "otherMessage": "Hello World!" }
+
+    - Attributes (OtherMessage)
+
+# Message [GET /message]
+
++ Response 200 (application/json)
+    Unparsable schema should fall back to Attributes
+
+    + Schema
+        {1234{}I'm unparsable}
+
+    + Attributes (Message)
+
+## Data structures
+
+# Message
+- message (string)
+
+# OtherMessage
+- otherMessage (string)

package/test/input/includes/resource-request-body-2.json

@@ -0,0 +1,3 @@
+{
+    "message": "Additional request" 
+}

package/test/input/includes/resource-request-body.json

@@ -0,0 +1,3 @@
+{
+    "message": "Hello world!" 
+}

package/test/input/includes/resource-request-schema.json

@@ -0,0 +1,9 @@
+{
+    "type": "object",
+    "properties": {
+        "message": {
+            "type": "string",
+            "description": "This is the message description "
+        }
+    }
+}

package/test/input/includes/resource-response-body-2.json

@@ -0,0 +1,3 @@
+{
+    "message": "Additional response" 
+}

package/test/input/includes/resource-response-body.json

@@ -0,0 +1,3 @@
+{
+    "message": "Hello world!" 
+}

package/test/input/includes/resource-response-schema.json

@@ -0,0 +1,9 @@
+{
+    "type": "object",
+    "properties": {
+        "message": {
+            "type": "string",
+            "description": "This is the message description "
+        }
+    }
+}