@openaddresses/batch-schema 7.1.0 → 7.2.0

package/CHANGELOG.md

@@ -10,6 +10,10 @@
 
 ## Version History
 
+### v7.2.0
+
+- :tada: Preliminary support for automatically generated an APIDoc definitions file
+
 ### v7.1.0
 
 - :bug: Only validate response on 200 status

package/lib/docs.js

@@ -0,0 +1,36 @@
+/**
+ * @class Docs
+ */
+export default class Docs extends Array {
+    push(parsed, schemas) {
+        const apiParams = [];
+        for (const key in schemas) {
+            if (key[0] === ':') {
+                apiParams.push(`* @apiParam {${schemas[key]}} ${key.slice(1)} param`);
+            }
+        }
+
+        super.push(
+            `
+                /**
+                 * @api {${parsed[0].toLowerCase()}} ${parsed[1]} ${schemas.name || parsed.join(' ')}
+                 * @apiVersion ${schemas.version || '1.0.0'}
+                 * @apiName ${parsed.join('-')}
+                 * @apiGroup ${schemas.group || 'Default'}
+                 * @apiPermission ${schemas.auth || 'Unknown'}
+                 *
+                 * @apidescription
+                 *   ${schemas.description || 'No Description'}
+                 *
+                 ${apiParams.join('\n')}
+                 *
+                 * ${schemas.query_url ? `@apiSchema (Query) {jsonschema=${schemas.query_url}} apiParam` : ''}
+                 * ${schemas.body_url ? `@apiSchema (Body) {jsonschema=${schemas.body_url}} apiParam` : ''}
+                 * ${schemas.res_url ? `@apiSchema {jsonschema=${schemas.res_url}} apiSuccess` : ''}
+                 */
+            `.split('\n')
+                .map((l) => l.trim())
+                .join('\n')
+        );
+    }
+}

package/lib/schema.js

@@ -7,6 +7,7 @@ import bodyparser from 'body-parser';
 
 import SchemaRoute from '../routes/schema.js';
 import Param from './param.js';
+import Docs from './docs.js';
 import Middleware from './middleware.js';
 
 /**
@@ -17,6 +18,8 @@ import Middleware from './middleware.js';
  * @param {String} opts.schemas Schemas Path
  * @param {boolean|string} [opts.logging=true] disable logging with false
  * @param {number} [opts.limit=50] body size limit in mb
+ *
+ * @param {URL} [opts.apidoc] apidoc file location
  */
 export default class Schemas {
     constructor(router, opts = {}) {
@@ -45,6 +48,8 @@ export default class Schemas {
 
         this.schemas = new Map();
         this.validate = this.validator.validate;
+
+        this.docs = new Docs();
     }
 
     async api() {
@@ -121,6 +126,8 @@ export default class Schemas {
         for (const type of ['body', 'query', 'res']) {
             if (!schemas[type]) continue;
 
+            // TODO: Write schemas to a tmp directory so blueprints & main schemas are in the same place
+            schemas[`${type}_url`] = '../schema/' + schemas[type];
             try {
                 schemas[type] = await $RefParser.dereference((new URL(`../schema/${schemas[type]}`, import.meta.url)).pathname);
             } catch (err) {
@@ -128,6 +135,8 @@ export default class Schemas {
             }
         }
 
+        this.docs.push(parsed, schemas);
+
         this.schemas.set(parsed.join(' '), schemas);
 
         const opts = {};
@@ -178,7 +187,11 @@ export default class Schemas {
         if (!schema.body) schema.body = null;
         if (!schema.res) schema.res = null;
 
-        return schema;
+        return {
+            query: schema.query,
+            body: schema.body,
+            res: schema.res
+        };
     }
 
     /**

package/package.json

@@ -3,7 +3,7 @@
     "type": "module",
     "root": true,
     "main": "index.js",
-    "version": "7.1.0",
+    "version": "7.2.0",
     "description": "Strongly Validated JSON Schema support for address",
     "repository": "git@github.com:openaddresses/batch-schema",
     "author": "ingalls <nick@ingalls.ca>",