@openaddresses/batch-schema 7.6.0 → 8.0.0

package/CHANGELOG.md

@@ -10,6 +10,14 @@
 
 ## Version History
 
+### v8.0.0
+
+- :data: Remove APIDoc support in favour of OpenAPI Route
+
+### v7.6.1
+
+- :bug: Explicit AJV strict: false
+
 ### v7.6.0
 
 - :tada: Update Core Deps

package/README.md

@@ -4,12 +4,6 @@
 
 ## Installation
 
-```sh
-yarn add @openaddresses/batch-schema
-```
-
-or
-
 ```sh
 npm i @openaddresses/batch-schema
 ```
@@ -75,6 +69,8 @@ Adds a route called `GET /schema` which allows the caller to get a list of endpo
 as well as full schema details for every route. If your API is public we recommend enabling this feature, however
 if you do not wish for API routes to be published, this feature is disabled unless called.
 
+Adds a route called `GET /openapi` which returns an OpenAPI / Swagger JSON Object
+
 ### schema.not_found
 
 Adds a middlware which will catch all routes that have not been defined and return

package/lib/middleware.js

@@ -6,6 +6,7 @@ import { ValidationError } from 'express-json-validator-middleware';
 import Generic from '@openaddresses/batch-generic';
 
 const ajv = addFormats(new Ajv({
+    strict: false,
     allErrors: true,
     removeAdditional: true
 }));

package/lib/openapi.js

@@ -0,0 +1,96 @@
+/**
+ * @class
+ */
+export default class Docs {
+    constructor(info) {
+        this.base = {
+            openapi: '3.0.3',
+            info: info || {
+                title: 'OpenAPI Schema',
+                version: '1.0.0'
+            },
+            paths: {}
+        };
+    }
+
+    push(parsed, schemas) {
+        let path = [];
+        const method = parsed[0].toLowerCase();
+
+        for (let sec of parsed[1].split('/')) {
+            for (const lit of ['.', '-']) { // These chars are used literally and can't be part of a param name
+                const mini = [];
+                for (const s of sec.split(lit)) {
+                    if (s[0] === ':') mini.push(`{${s}}`);
+                    else mini.push(s);
+                }
+                sec = mini.join(lit);
+            }
+            path.push(sec);
+        }
+        path = path.join('/');
+
+
+        if (!this.base.paths[path]) this.base.paths[path] = {};
+
+        if (this.base.paths[path][method]) throw new Error(`Duplicate Path: ${parsed.join(' ')}`);
+
+        const document = {
+            summary: schemas.description || 'No Description',
+            tags: [schemas.group || 'Default'],
+            parameters: [],
+            responses: {
+                200: {
+                    description: 'Successful Response'
+                }
+            }
+        };
+
+        for (const key in schemas) {
+            if (key[0] === ':') {
+                document.parameters.push({
+                    in: 'path',
+                    name: key,
+                    schema: {
+                        type: schemas[key]
+                    },
+                    required: true
+                });
+            }
+        }
+
+        if (schemas.query && schemas.query.type === 'object') {
+            for (const name in (schemas.query.properties || {})) {
+                const query = schemas.query.properties[name];
+                document.parameters.push({
+                    in: 'query',
+                    name,
+                    schema: query,
+                    required: query.required || (schemas.query.required || []).includes(name),
+                    description: query.description || 'No Description'
+                });
+            }
+        }
+
+        if (schemas.res) {
+            document.responses['200'].content = {
+                'application/json': {
+                    schema: schemas.res
+                }
+            };
+        }
+
+        if (schemas.body) {
+            document.requestBody = {
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: schemas.body
+                    }
+                }
+            };
+        }
+
+        this.base.paths[path][method] = document;
+    }
+}

package/lib/schema.js

@@ -1,5 +1,5 @@
 import { Validator } from 'express-json-validator-middleware';
-import $RefParser from 'json-schema-ref-parser';
+import $RefParser from '@apidevtools/json-schema-ref-parser';
 import fs from 'fs';
 import path from 'path';
 import morgan from 'morgan';
@@ -7,7 +7,7 @@ import bodyparser from 'body-parser';
 
 import SchemaRoute from '../routes/schema.js';
 import Param from './param.js';
-import Docs from './docs.js';
+import Docs from './openapi.js';
 import Middleware from './middleware.js';
 
 /**

package/package.json

@@ -3,7 +3,7 @@
     "type": "module",
     "root": true,
     "main": "index.js",
-    "version": "7.6.0",
+    "version": "8.0.0",
     "description": "Strongly Validated JSON Schema support for address",
     "repository": "git@github.com:openaddresses/batch-schema",
     "author": "ingalls <nick@ingalls.ca>",
@@ -18,23 +18,23 @@
         "doc": "documentation build index.js -f html -o docs && documentation lint index.js"
     },
     "dependencies": {
+        "@apidevtools/json-schema-ref-parser": "^10.0.0",
         "@openaddresses/batch-error": "^2.1.2",
         "ajv": "^8.6.3",
         "ajv-formats": "^2.1.1",
         "body-parser": "^1.20.0",
         "express": "^4.17.1",
         "express-json-validator-middleware": "^3.0.0",
-        "glob": "^8.0.0",
-        "json-schema-ref-parser": "^9.0.9",
-        "morgan": "^1.10.0",
-        "tape": "^5.3.1"
+        "glob": "^9.0.0",
+        "morgan": "^1.10.0"
     },
     "peerDependencies": {
         "@openaddresses/batch-generic": "x.x.x"
     },
     "devDependencies": {
-        "documentation": "^13.2.5",
+        "documentation": "^14.0.1",
         "eslint": "^8.0.1",
-        "eslint-plugin-node": "^11.0.0"
+        "eslint-plugin-node": "^11.0.0",
+        "tape": "^5.3.1"
     }
 }

package/routes/schema.js

@@ -1,26 +1,16 @@
 import Err from '@openaddresses/batch-error';
 
 export default async function router(schema) {
-    /**
-     * @api {get} /api/schema List Schemas
-     * @apiVersion 1.0.0
-     * @apiName ListSchemas
-     * @apiGroup Schemas
-     * @apiPermission public
-     *
-     * @apiDescription
-     *     List all JSON Schemas in use
-     *     With no parameters this API will return a list of all the endpoints that have a form of schema validation
-     *     If the url/method params are used, the schemas themselves are returned
-     *
-     *     Note: If url or method params are used, they must be used together
-     *
-     * @apiSchema (Query) {jsonschema=../schema/req.query.ListSchema.json} apiParam
-     * @apiSchema {jsonschema=../schema/res.ListSchema.json} apiSuccess
-     */
     await schema.get('/schema', {
         query: 'req.query.ListSchema.json',
-        res: 'res.ListSchema.json'
+        res: 'res.ListSchema.json',
+        description: `
+            List all JSON Schemas in use
+            With no parameters this API will return a list of all the endpoints that have a form of schema validation
+            If the url/method params are used, the schemas themselves are returned
+
+            Note: If url or method params are used, they must be used together
+        `
     }, async (req, res) => {
         try {
             if (req.query.url && req.query.method) {
@@ -34,4 +24,14 @@ export default async function router(schema) {
             return Err.respond(err, res);
         }
     });
+
+    await schema.get('/openapi', {
+        description: 'Return a OpenAPI Schema for the API'
+    }, async (req, res) => {
+        try {
+            return res.json(schema.docs.base);
+        } catch (err) {
+            return Err.respond(err, res);
+        }
+    });
 }

package/test/schema.srv.test.js

@@ -31,6 +31,11 @@ test('GET: api/schema', async (t) => {
                 body: false,
                 query: true,
                 res: true
+            },
+            'GET /openapi': {
+                body: false,
+                query: false,
+                res: false
             }
         });
     } catch (err) {

package/test/schema.test.js

@@ -3,7 +3,7 @@ import path from 'path';
 import test from 'tape';
 
 import glob from 'glob';
-import $RefParser from 'json-schema-ref-parser';
+import $RefParser from '@apidevtools/json-schema-ref-parser';
 import Ajv from 'ajv';
 
 const ajv = new Ajv({

package/lib/docs.js

@@ -1,36 +0,0 @@
-/**
- * @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')
-        );
-    }
-}