feat: openai compliant option

Signed-off-by: Mike Ralphson <[email protected]>

Author: MikeRalphson

README.md

@@ -12,12 +12,14 @@ Usage: openapi-extract [options] {infile} [{outfile}]
 Options:
   -h, --help             Show help                                     [boolean]
   --version              Show version number                           [boolean]
+  --openai               make the definition OpenAI compliant          [boolean]
   --server               include server information                    [boolean]
   --shard                shard the input to an output directory         [string]
   -p, --path             the path to extract                            [string]
   -o, --operationid      the operationIds to extract                     [array]
   -m, --method           the method to extract for the given path       [string]
   -i, --info             copy full info object, otherwise minimal      [boolean]
+  -d, --removeDocs       remove all externalDocs properties            [boolean]
   -r, --removeExamples   remove all example/examples properties        [boolean]
   -x, --removeExtensions remove all x- extension properties            [boolean]
   -s, --security         include security information                  [boolean]
@@ -42,8 +44,16 @@ The `options` object takes the same values as the CLI, for these keys and defaul
 *   path = ''
 *   method = ''
 *   info = false
+*   openai = false
+*   removeDocs = false
 *   removeExamples = false
+*   removeExtensions = false
 *   server = false
 *   security = false
 *   operationid = []
 
+## OpenAI compliant mode
+
+This option turns on the following rules:
+
+1. The `description` properties must have a maximum length of 300 characters

index.js

@@ -8,8 +8,8 @@ const { AList } = require('./lib/AList.js');
 // TODO add a memoized cache
 
 function clean(obj, property) {
-    if (obj && (typeof obj[property] === 'object') && (!Object.keys(obj[property]).length)) {
-        delete obj[property];
+    if (obj && (!Array.isArray(obj[property])) && (typeof obj[property] === 'object') && (!Object.keys(obj[property]).length)) {
+        if (property !== 'paths') delete obj[property];
     }
     return obj;
 }
@@ -36,10 +36,12 @@ function extract(obj, options) {
 
     const defaults = {};
     defaults.info = false;
+    defaults.removeDocs = false;
     defaults.removeExamples = false;
     defaults.removeExtensions = false;
     defaults.server = false;
     defaults.security = false;
+    defaults.openai = false;
     defaults.operationid = [];
     options = Object.assign({},defaults,options);
 
@@ -116,13 +118,13 @@ function extract(obj, options) {
     }
     else {
         paths = {};
-        paths[options.path] = {};
+        if (options.path) paths[options.path] = {};
         if (options.method) paths[options.path][options.method] = {};
         if (options.method && obj.paths[options.path][options.method]) {
             paths[options.path][options.method] = clone(obj.paths[options.path][options.method]);
             deref(paths[options.path][options.method],src,obj);
         }
-        else {
+        else if (options.path) {
             for (let o in obj.paths[options.path]) {
                 if ((o !== 'description') && (o !== 'summary') &&
                     (!o.startsWith('x-'))) {
@@ -161,6 +163,15 @@ function extract(obj, options) {
     deref(src.parameters,src,obj);
     deref(src.components,src,obj);
 
+    if (options.openai) {
+        recurse(src,{},function(obj,key,state){
+          if (obj && key === 'description' && obj.description.length > 300) {
+              state.parent[state.pkey].description = obj.description.substring(0,300);
+          }
+        });
+    }
+
+    clean(src,'paths');
     clean(src,'definitions');
     clean(src,'headers');
     clean(src,'responses');
@@ -171,20 +182,26 @@ function extract(obj, options) {
     clean(src.components,'schemas');
     clean(src,'components');
 
+    const al = new AList(src);
     if (options.removeExamples) {
-        const al = new AList(src);
         for (let [value,parents] of al) {
             AList.deleteProperty(value, 'example');
             AList.deleteProperty(value, 'examples');
         }
     }
 
     if (options.removeExtensions) {
-        const al = new AList(src);
         for (let [value,parents] of al) {
             AList.deletePrefix(value, 'x-');
         }
     }
+
+    if (options.removeDocs) {
+        for (let [value,parents] of al) {
+            AList.deleteProperty(value, 'externalDocs');
+        }
+    }
+
     return src;
 }
 

openapi-extract.js

@@ -21,6 +21,8 @@ let argv = require('yargs')
     .string('path')
     .alias('p','path')
     .describe('path','the path to extract')
+    .boolean('openai')
+    .describe('openai','make definition OpenAI compliant')
     .array('operationid')
     .alias('o','operationid')
     .describe('operationid','the operationIds to extract')
@@ -35,6 +37,9 @@ let argv = require('yargs')
     .boolean('security')
     .alias('s','security')
     .describe('security','include security information')
+    .boolean('removeDocs')
+    .alias('d','removeDocs')
+    .describe('removeDocs','remove all externalDocs properties')
     .boolean('removeExamples')
     .alias('r','removeExamples')
     .describe('removeExamples','remove all example/examples properties')

test/longdesc/input.yaml

@@ -0,0 +1,6 @@
+openapi: 3.1.0
+info:
+    title: API
+    version: 1.0.0
+    description: 1234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890 This should get truncated...
+paths: {}

test/longdesc/options.yaml

@@ -0,0 +1,2 @@
+info: true
+openai: true

test/longdesc/output.yaml

@@ -0,0 +1,6 @@
+openapi: 3.1.0
+info:
+    title: API
+    version: 1.0.0
+    description: "123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890"
+paths: {}