@openaddresses/batch-schema 7.1.0 → 7.3.0

package/CHANGELOG.md

@@ -10,6 +10,14 @@
 
 ## Version History
 
+### v7.3.0
+
+- :arrow_up: `res.json` will automatically serialize Generic objects
+
+### 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/middleware.js

@@ -3,6 +3,7 @@ import Param from './param.js';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import { ValidationError } from 'express-json-validator-middleware';
+import Generic from '@openaddresses/batch-generic';
 
 const ajv = addFormats(new Ajv({
     allErrors: true,
@@ -99,6 +100,7 @@ export default class Middleware {
 
     /**
      * Express middleware to validate the response body
+     * and optionally serialize Generic object to JSON
      *
      * @param {Object} schema JSON Schema
      *
@@ -110,6 +112,10 @@ export default class Middleware {
         return function (req, res, next) {
             const json = res.json;
             res.json = function(obj) {
+                if (obj instanceof Generic && typeof obj.serialize === 'function') {
+                    obj = obj.serialize();
+                }
+
                 if (res.statusCode === null || res.statusCode === 200) {
                     validate(obj);
                 }

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.3.0",
     "description": "Strongly Validated JSON Schema support for address",
     "repository": "git@github.com:openaddresses/batch-schema",
     "author": "ingalls <nick@ingalls.ca>",
@@ -29,6 +29,9 @@
         "morgan": "^1.10.0",
         "tape": "^5.3.1"
     },
+    "peerDependencies": {
+        "@openaddresses/batch-generic": "x.x.x"
+    },
     "devDependencies": {
         "documentation": "^13.2.5",
         "eslint": "^8.0.1",