added cli option to inline references

fix #63
cebe · Dec 31, 2020 · 310de02 · 310de02
1 parent 38d985a
commit 310de02
Show file tree

Hide file tree

Showing 3 changed files with 51 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -55,14 +55,26 @@ do awesome work:
                    Exits with code 2 on validation errors, 1 on other errors and 0 on success.
 
         convert    Convert a JSON or YAML input file to JSON or YAML output file.
-                   References are being resolved so the output will be a single API Description file.
 
                    If no input file is specified input will be read from STDIN.
                    If no output file is specified output will be written to STDOUT.
                    The tool will try to auto-detect the content type of the input and output file, but may fail
                    to do so, you may specify --read-yaml or --read-json to force the input file type.
                    and --write-yaml or --write-json to force the output file type.
 
+                   By default all references are resolved (replaced with the object refered to). You can control
+                   handling of references with the following arguments:
+
+                   --resolve-none      Do not resolve references.
+                   --resolve-external  Only resolve references that point to external files.
+                                       This process is often referred to as "inlining".
+                   --resolve-all       Resolve all references (default).
+                                       Recursive pointers will stay references.
+
+        inline     Convert a JSON or YAML input file to JSON or YAML output file and
+                   resolve all external references. The output will be a single API Description file.
+                   This is a shortcut for calling convert --resolve-external.
+
         help       Shows this usage information.
 
       Options:
@@ -71,6 +83,7 @@ do awesome work:
         --read-yaml   force reading input as YAML. Auto-detect if not specified.
         --write-json  force writing output as JSON. Auto-detect if not specified.
         --write-yaml  force writing output as YAML. Auto-detect if not specified.
+        -s, --silent  silent mode. Will hide all success/information messages and only print errors.
 
 
 ### Reading API Description Files

diff --git a/bin/php-openapi b/bin/php-openapi
@@ -33,6 +33,7 @@ $inputFormat = null;
 $outputFile = null;
 $outputFormat = null;
 $silentMode = false;
+$referenceMode = ReferenceContext::RESOLVE_MODE_ALL;
 foreach($argv as $k => $arg) {
     if ($k == 0) {
         continue;
@@ -54,6 +55,15 @@ foreach($argv as $k => $arg) {
                     error("Conflicting arguments: only one of --read-json or --read-yaml is allowed!", "usage");
                 }
             break;
+            case '--resolve-none':
+                $referenceMode = false;
+            break;
+            case '--resolve-external':
+                $referenceMode = ReferenceContext::RESOLVE_MODE_INLINE;
+            break;
+            case '--resolve-all':
+                $referenceMode = ReferenceContext::RESOLVE_MODE_ALL;
+            break;
             case '--write-yaml':
                 if ($outputFormat === null) {
                     $outputFormat = 'yaml';
@@ -89,6 +99,11 @@ foreach($argv as $k => $arg) {
     } else {
         if ($command === null) {
             $command = $arg;
+            // inline is an alias for "convert --resolve-external"
+            if ($command === 'inline') {
+                $command = 'convert';
+                $referenceMode = ReferenceContext::RESOLVE_MODE_INLINE;
+            }
         } elseif ($inputFile === null) {
             $inputFile = $arg;
         } elseif ($outputFile === null) {
@@ -109,9 +124,7 @@ switch ($command) {
         $openApi = read_input($inputFile, $inputFormat);
         $referenceContext = new ReferenceContext($openApi, $inputFile ? realpath($inputFile) : '');
         $referenceContext->throwException = false;
-        // TODO apply reference context mode
-//        $referenceContext->mode = ReferenceContext::RESOLVE_MODE_ALL;
-//        $referenceContext->mode = ReferenceContext::RESOLVE_MODE_INLINE;
+        $referenceContext->mode = ReferenceContext::RESOLVE_MODE_INLINE;
         $openApi->resolveReferences($referenceContext);
 
         $openApi->setDocumentContext($openApi, new \cebe\openapi\json\JsonPointer(''));
@@ -189,12 +202,13 @@ switch ($command) {
 
         $openApi = read_input($inputFile, $inputFormat);
         try {
-            // TODO apply reference context mode
-//            $referenceContext->mode = ReferenceContext::RESOLVE_MODE_ALL;
-//            $referenceContext->mode = ReferenceContext::RESOLVE_MODE_INLINE;
             // set document context for correctly converting recursive references
             $openApi->setDocumentContext($openApi, new \cebe\openapi\json\JsonPointer(''));
-            $openApi->resolveReferences();
+            if ($referenceMode) {
+                $referenceContext = new ReferenceContext($openApi, $inputFile ? realpath($inputFile) : '');
+                $referenceContext->mode = $referenceMode;
+                $openApi->resolveReferences($referenceContext);
+            }
         } catch (\cebe\openapi\exceptions\UnresolvableReferenceException $e) {
             error("[\e[33m{$e->context}\e[0m] " . $e->getMessage());
         }
@@ -310,14 +324,26 @@ Usage:
                Exits with code 2 on validation errors, 1 on other errors and 0 on success.
 
     \Bconvert\C    Convert a JSON or YAML input file to JSON or YAML output file.
-               References are being resolved so the output will be a single API Description file.
 
                If no input file is specified input will be read from STDIN.
                If no output file is specified output will be written to STDOUT.
                The tool will try to auto-detect the content type of the input and output file, but may fail
                to do so, you may specify \Y--read-yaml\C or \Y--read-json\C to force the input file type.
                and \Y--write-yaml\C or \Y--write-json\C to force the output file type.
 
+               By default all references are resolved (replaced with the object refered to). You can control
+               handling of references with the following arguments:
+
+               \Y--resolve-none\C      Do not resolve references.
+               \Y--resolve-external\C  Only resolve references that point to external files.
+                                   This process is often referred to as "inlining".
+               \Y--resolve-all\C       Resolve all references (default).
+                                   Recursive pointers will stay references.
+
+    \Binline\C     Convert a JSON or YAML input file to JSON or YAML output file and
+               resolve all external references. The output will be a single API Description file.
+               This is a shortcut for calling \Bconvert\C \Y--resolve-external\C.
+
     \Bhelp\C       Shows this usage information.
 
   Options:

diff --git a/composer.json b/composer.json
@@ -27,7 +27,7 @@
 		"cebe/indent": "*",
 		"phpunit/phpunit": "^6.5 || ^7.5 || ^8.5 || ^9.4",
 
-		"oai/openapi-specification": "3.0.2",
+		"oai/openapi-specification": "3.0.3",
 		"mermade/openapi3-examples": "1.0.0",
 		"apis-guru/openapi-directory": "1.0.0",
 		"nexmo/api-specification": "1.0.0",
@@ -51,11 +51,11 @@
 			"type": "package",
 			"package": {
 				"name": "oai/openapi-specification",
-				"version": "3.0.2",
+				"version": "3.0.3",
 				"source": {
 					"url": "https://github.com/OAI/OpenAPI-Specification",
 					"type": "git",
-					"reference": "3.0.2"
+					"reference": "3.0.3"
 				}
 			}
 		},