@sleeksky/alt-swagger 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 SleekSky LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# Spec API
+
+Quickly spec your APIs for Swagger / OpenAPI interface. Uses @sleeksky/alt-schema for specifying JSON schema.
+
+# Example
+```JavaScript
+let refRequest = docs.ref.schema('example','{id:i:1,name:s:foo,label:{id:i:2,name:?s:bar},arr:[{a:b:false}]}');
+
+docs.put('/:id').tag("dot-notation").req(refRequest).res(200, '{hello,world}');
+```
+![](https://i.ibb.co/ypWxGZJ/spec-api-ss1.png)
+# Installation
+
+npm install -s @sleeksky/alt-swagger
+
+const docs = require('@sleeksky/alt-swagger');
+
+# License
+
+MIT © SleekSky

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@sleeksky/alt-swagger",
+  "version": "2.0.0",
+  "description": "Quickly spec your APIs for Swagger / OpenAPI interface",
+  "main": "./src/index.js",
+  "scripts": {
+    "test": "mocha",
+    "cover": "nyc --check-coverage npm run test",
+    "prepublish": "npm run test"
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sleeksky-dev/alt-swagger"
+  },
+  "keywords": [
+    "swagger",
+    "open-api",
+    "api-spec",
+    "express",
+    "javascript"
+  ],
+  "author": "Yusuf <yusuf@sleeksky.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/sleeksky-dev/alt-swagger/issues"
+  },
+  "homepage": "https://github.com/sleeksky-dev/alt-swagger#readme",
+  "devDependencies": {
+    "chai": "^4.1.2",
+    "cross-env": "^5.1.3",
+    "express": "^4.17.1",
+    "mocha": "^6.1.3",
+    "nyc": "^13.3.0",
+    "swagger-ui-express": "^4.1.6"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21"
+  },
+  "peerDependencies": {
+    "@sleeksky/alt-schema": "2.x"
+  }
+}

package/src/index.js

@@ -0,0 +1,146 @@
+/**
+  Author: Yusuf Bhabhrawala
+ */
+require("./utils");
+const _ = require("lodash");
+const { toSwaggerSchema, pathParameters, toParameter} = require("./utils")
+
+const paths = {};
+const components = {};
+const tags = [];
+const servers = [];
+
+function reset() {
+  Object.keys(paths).forEach((key) => delete paths[key]);
+  Object.keys(components).forEach((key) => delete paths[key]);
+  tags.splice(0, tags.length);
+  servers.splice(0, servers.length);
+}
+
+function server(url, description) {
+  servers.push({ url, description });
+}
+
+function api(opt) {
+  const spec = { parameters: [], responses: {}, description: "" };
+  const pathParams = pathParameters(opt.path);
+  if (pathParams.length > 0) spec.parameters = pathParams;
+
+  _.set(paths, `${opt.path}.${opt.method}`, spec);
+
+  let ext = {};
+
+  const req = (flatSch) => {
+    let schema = flatSch.match(/^#/) ? { $ref: flatSch } : toSwaggerSchema(flatSch);
+    spec.requestBody = {
+      content: { "application/json": { schema } },
+    };
+    return ext;
+  };
+  const res = (code, flatSch) => {
+    let schema = flatSch.match(/^#/) ? { $ref: flatSch } : toSwaggerSchema(flatSch);
+    spec.responses[code] = {
+      content: { [schema.type === "string" ? "text/plain" : "application/json"]: { schema } },
+      description: "",
+    };
+    return ext;
+  };
+  const query = (strArr) => {
+    if (!_.isArray(strArr)) strArr = strArr.split(",");
+    strArr.forEach((str) => {
+      spec.parameters.push(toParameter('query',str));
+    });
+    return ext;
+  };
+  const header = (strArr) => {
+    if (!_.isArray(strArr)) strArr = strArr.split(",");
+    strArr.forEach((str) => {
+      spec.parameters.push(toParameter('header',str));
+    });
+    return ext;
+  };
+  const tag = (str) => { spec.tags = [str]; return ext; };
+  const summary = (str) => { spec.summary = str; return ext; };
+  const desc = (str) => { spec.description = str; return ext; };
+  const deprecate = () => { spec.deprecated = true; return ext; };
+
+  Object.assign(ext, { req, res, query, header, tag, summary, desc, deprecate });
+
+  // support all ext in parameters
+  Object.keys(ext).forEach(k => {
+    if (opt[k]) ext[k](opt[k]);
+  });
+  Object.keys(opt).filter(k => k.match(/^[0-9]+$/)).forEach(k => ext.res(k, opt[k]));
+
+  return ext;
+}
+
+function get(path = "", opt = {}) {
+  opt.method = "get";
+  opt.path = path;
+  return api(opt);
+}
+
+function post(path = "", opt = {}) {
+  opt.method = "post";
+  opt.path = path;
+  return api(opt);
+}
+
+function put(path = "", opt = {}) {
+  opt.method = "put";
+  opt.path = path;
+  return api(opt);
+}
+
+function patch(path = "", opt = {}) {
+  opt.method = "patch";
+  opt.path = path;
+  return api(opt);
+}
+
+function del(path = "", opt = {}) {
+  opt.method = "delete";
+  opt.path = path;
+  return api(opt);
+}
+
+function _ref({ type, name, def }) {
+  components[type] = components[type] || {};
+  components[type][name] = def;
+  return `#/components/${type}/${name}`;
+}
+
+const ref = {
+  schema(name, flatSch) {
+    return _ref({ type: "schemas", name, def: toSwaggerSchema(flatSch) });
+  }
+}
+
+function tag(name, description) {
+  tags.push({ name, description });
+}
+
+function swaggerDoc(title = "API Docs") {
+  return {
+    info: { title, version: "1.0.0" },
+    openapi: "3.0.0",
+    servers,
+    tags,
+    paths,
+    components,
+  };
+}
+
+module.exports = {
+  tag,
+  server,
+  ref,
+  get,
+  post,
+  put,
+  patch,
+  del,
+  swaggerDoc,
+  reset,
+};

package/src/utils.js

@@ -0,0 +1,93 @@
+/**
+Author: Yusuf Bhabhrawala
+ */
+const _ = require("lodash");
+
+const {typeShape} = require("@sleeksky/alt-schema");
+
+const TYPES = {i: "integer", s: "string", b: "boolean", n: "number", o: "object", a: "array"};
+const RX_OBJ = /(\{[^\{\}\[\]]+\})/;
+const RX_ARR = /(\[[^\{\}\[\]]+\])/;
+const RX_NESTED = /^\:?(\$[0-9]+)$/;
+const RX_FLAT_ARR = /^\[([^\{\}\[\]]+)\]$/;
+const RX_FLAT_OBJ = /^\{([^\{\}\[\]]+)\}$/;
+
+function toSwaggerSchema(str) {
+
+  function traverse(schema, obj) {
+    if (_.isArray(obj)) {
+      schema.type = "array";
+      schema.items = {};
+      traverse(schema.items, obj[0]);
+    } else if (_.isObject(obj)) {
+      schema.type = "object";
+      schema.properties = {};
+      _.forOwn(obj, (v, k) => {
+        schema.properties[k] = {};
+        traverse(schema.properties[k], v);
+      });
+    } else {
+      let [optional, type, def] = obj.split(":");
+      optional = (optional === '?') ? true : false;
+      if (['string','number','boolean','integer','array','object'].indexOf(type) < 0) type = "string"; 
+      schema.type = type;
+      if (def !== '') {
+        if (type === 'number' || type === 'integer') def = def*1;
+        if (type === 'boolean') def = ['true','1'].indexOf(def) > -1 ? true : false;
+        schema.default = def;
+      } else if (optional) {
+        schema.default = null;
+      }
+      if (!optional) schema.required = true;
+    }
+  }
+
+  try {
+    let obj = typeShape(str);
+    let schema = {};
+    traverse(schema, obj);
+    return schema;
+  } catch (error) {
+    throw new Error(`Malformed schema: ${str}`);
+  }
+}
+
+function pathParameters(str) {
+  let params = [];
+  const RX_BRACE = /\{([^\}]+)\}/g;
+  const RX_COLON = /\:([^\/]+)/g;
+  let matches = str.match(RX_BRACE);
+  if (!matches) matches = str.match(RX_COLON);
+  if (matches) {
+    params = matches.map(m => {
+      let p = m.replace(/[\{\}\:]/g, "");
+      return { in: "path", name: p, schema: { type: "string" }, required: true };
+    });
+  }
+  return params;
+}
+
+// header:?token
+function toParameter(inType, str) {
+  if (!_.isString(str)) return str;
+  str = str.replace(/ /g, "");
+  let [name, type, def] = str.split(":");
+  let required = true;
+  if (type && type.match(/^\?/)) {
+    type = type.replace(/^\?/, "");
+    required = false;
+  }
+  if (type && TYPES[type]) type = TYPES[type];
+  else type = "string";
+  let schema = { type };
+  if (def) schema.default = def;
+
+  return {
+    name,
+    in: inType,
+    required,
+    schema
+  }
+}
+
+module.exports = {toSwaggerSchema, pathParameters, toParameter};