Add JSDoc generator (#25)

Author: vearutop

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.8.4] - 2021-04-07
+
+### Added
+- Generation of JSDoc type definitions from JSON Schema with `gen-jsdoc`.
+
 ## [1.8.3] - 2020-12-14
 
 ### Fixed

README.md

@@ -2,7 +2,9 @@
 
 <img align="right" width="100px" height="100px" alt="Swiss Knife" src="./knife.svg">
 
-A CLI app to find unordered diff between two `JSON` documents (based on [`swaggest/json-diff`](https://github.com/swaggest/json-diff)), generate JSON Schema and Go/PHP code, pretty print, minify, yaml convert, etc....
+A CLI app to find unordered diff between two `JSON` documents (based
+on [`swaggest/json-diff`](https://github.com/swaggest/json-diff)), generate JSON Schema and Go/PHP code, pretty print,
+minify, yaml convert, etc....
 
 [![Build Status](https://travis-ci.org/swaggest/json-cli.svg?branch=master)](https://travis-ci.org/swaggest/json-cli)
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/swaggest/json-cli/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/swaggest/json-cli/?branch=master)
@@ -14,17 +16,20 @@ A CLI app to find unordered diff between two `JSON` documents (based on [`swagge
 
 ## Purpose
 
- * To simplify changes review between two `JSON` files you can use a standard `diff` tool on rearranged pretty-printed `JSON`.
- * To detect breaking changes by analyzing removals and changes from original `JSON`.
- * To keep original order of object sets (for example `swagger.json` [parameters](https://swagger.io/docs/specification/describing-parameters/) list).
- * To make and apply JSON Patches, specified in [RFC 6902](http://tools.ietf.org/html/rfc6902) from the IETF.
- * To convert between YAML/JSON/PHP serialization.
- * To resolve `JSON Pointer` to data.
- * To resolve `JSON Pointer` to file position.
- * To validate JSON data against [`JSON Schema`](http://json-schema.org/).
- * To [generate or update](#buildschema) JSON Schema with instance value(s).
- * To [render](#gengo) `JSON Schema` as [`Go`](http://golang.org/) structure.
- * To [render](#genphp) `JSON Schema` as `PHP` classes.
+* To simplify changes review between two `JSON` files you can use a standard `diff` tool on rearranged
+  pretty-printed `JSON`.
+* To detect breaking changes by analyzing removals and changes from original `JSON`.
+* To keep original order of object sets (for
+  example `swagger.json` [parameters](https://swagger.io/docs/specification/describing-parameters/) list).
+* To make and apply JSON Patches, specified in [RFC 6902](http://tools.ietf.org/html/rfc6902) from the IETF.
+* To convert between YAML/JSON/PHP serialization.
+* To resolve `JSON Pointer` to data.
+* To resolve `JSON Pointer` to file position.
+* To validate JSON data against [`JSON Schema`](http://json-schema.org/).
+* To [generate or update](#buildschema) JSON Schema with instance value(s).
+* To [render](#gengo) `JSON Schema` as [`Go`](http://golang.org/) structure.
+* To [render](#genphp) `JSON Schema` as `PHP` classes.
+* To [render](#genjsdoc) `JSON Schema` as `JSDoc` type definitions.
 
 ## Installation
 
@@ -60,6 +65,7 @@ Usage:
 ```
 
 Input paths can be .json/.yaml/.yml/.serialized files, file format is detected by file extension:
+
 * `.json` JSON
 * `.yaml`, `.yml` YAML
 * `.serialized` PHP serialization format
@@ -178,7 +184,6 @@ json-cli rearrange tests/assets/original.json tests/assets/new.json --rearrange-
 >     "key5": "wat"
 ```
 
-
 #### Show difference between two JSON documents
 
 ```
@@ -266,7 +271,8 @@ Options:
    --eol               Add line break to the output         
 ```
 
-Bash command to minify all JSON files in current directory. 
+Bash command to minify all JSON files in current directory.
+
 ```
 for f in *.json; do json-cli minify $f --output $f; done
 ```
@@ -348,6 +354,7 @@ Usage:
 ```
 
 Example:
+
 ```
 json-cli validate-schema tests/assets/sample-data.json tests/assets/sample-schema.json
 Data is invalid
@@ -386,6 +393,7 @@ Options:
 ```
 
 Basic example:
+
 ```
 json-cli build-schema tests/assets/original.json 
 
@@ -413,7 +421,7 @@ Usage:
    schema   Path to JSON schema file
 
 Options: 
-   --ptr-in-schema <ptrInSchema...>          JSON pointers to structure in in root schema, default #
+   --ptr-in-schema <ptrInSchema...>          JSON pointers to structure in root schema, default #
    --def-ptr <defPtr...>                     Definitions pointers to strip from symbol names, default #/definitions
    --patches <patches...>                    JSON patches to apply to schema file before processing, merge patches are also supported
    --output <output>                         Path to output .go file, STDOUT is used by default
@@ -440,6 +448,7 @@ Example:
 ```
 json-cli gen-go http://json-schema.org/learn/examples/address.schema.json
 ```
+
 ```
 // Code generated by github.com/swaggest/json-cli v1.6.3, DO NOT EDIT.
 
@@ -462,7 +471,7 @@ type Structure struct {
 }
 ```
 
-Advanced example: 
+Advanced example:
 
 ```
 json-cli gen-go "https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0-rc1/examples/1.2.0/streetlights.yml" \
@@ -555,7 +564,7 @@ Usage:
    schema   Path to JSON schema file
 
 Options: 
-   --ptr-in-schema <ptrInSchema...>           JSON pointers to structure in in root schema, default #
+   --ptr-in-schema <ptrInSchema...>           JSON pointers to structure in root schema, default #
    --def-ptr <defPtr...>                      Definitions pointers to strip from symbol names, default #/definitions
    --patches <patches...>                     JSON patches to apply to schema file before processing, merge patches are also supported
    --ns <ns>                                  Namespace to use for generated classes, example \MyClasses
@@ -568,7 +577,7 @@ Options:
    --build-additional-properties-accessors    Build accessors for additionalProperties
 ```
 
-Advanced example: 
+Advanced example:
 
 ```
 mkdir ./StreetLights
@@ -698,3 +707,44 @@ class TurnOnOffPayload extends ClassStructure
     }
 }
 ```
+
+#### <a name="genjsdoc"></a> Generate `JSDoc` type definitions from `JSON Schema`.
+
+```
+v1.8.4 json-cli gen-jsdoc
+JSON CLI tool, https://github.com/swaggest/json-cli
+Generate JSDoc code from JSON schema
+Usage: 
+   json-cli gen-jsdoc <schema>
+   schema   Path to JSON schema file
+   
+Options: 
+   --ptr-in-schema <ptrInSchema...>   JSON pointers to structure in root schema, default #                                 
+   --def-ptr <defPtr...>              Definitions pointers to strip from symbol names, default #/definitions                  
+   --patches <patches...>             JSON patches to apply to schema file before processing, merge patches are also supported
+```
+
+Example:
+
+```
+json-cli gen-jsdoc "https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0-rc1/examples/1.2.0/streetlights.yml" \
+    --ptr-in-schema "#/components/messages/lightMeasured/payload" "#/components/messages/turnOnOff/payload" \
+    --def-ptr "#/components/schemas"
+```
+
+```
+/**
+ * @typedef ComponentsMessagesLightMeasuredPayload
+ * @type {object}
+ * @property {number} lumens - Light intensity measured in lumens.
+ * @property {string} sentAt - Date and time when the message was sent.
+ */
+
+/**
+ * @typedef ComponentsMessagesTurnOnOffPayload
+ * @type {object}
+ * @property {string} command - Whether to turn on or off the light.
+ * @property {string} sentAt - Date and time when the message was sent.
+ */
+
+```

composer.json

@@ -17,7 +17,7 @@
     "salsify/json-streaming-parser": "^7.0",
     "swaggest/json-schema": "^0.12.21",
     "swaggest/go-code-builder": "^0.4.42",
-    "swaggest/php-code-builder": "^0.2.8",
+    "swaggest/php-code-builder": "^0.2.29",
     "swaggest/code-builder": "^0.3.2",
     "swaggest/json-schema-maker": "^0.3.4"
   },

composer.lock

@@ -7,7 +7,7 @@
 
 class App extends Command\Application
 {
-    public static $ver = 'v1.8.3';
+    public static $ver = 'v1.8.4';
 
     public $diff;
     public $apply;
@@ -21,6 +21,7 @@ class App extends Command\Application
     public $validateSchema;
     public $genGo;
     public $genPhp;
+    public $genJSDoc;
     public $buildSchema;
 
     /**
@@ -45,6 +46,7 @@ static function setUpCommands(Definition $definition, $commandDefinitions)
         $commandDefinitions->validateSchema = ValidateSchema::definition();
         $commandDefinitions->genGo = GenGo::definition();
         $commandDefinitions->genPhp = GenPhp::definition();
+        $commandDefinitions->genJSDoc = GenJSDoc::definition();
         $commandDefinitions->buildSchema = BuildSchema::definition();
     }
 }

src/App.php

@@ -5,8 +5,6 @@
 use Swaggest\JsonCli\Json\LoadFile;
 use Swaggest\JsonCli\JsonSchema\ResolverMux;
 use Swaggest\JsonDiff\Exception;
-use Swaggest\JsonDiff\JsonMergePatch;
-use Swaggest\JsonDiff\JsonPatch;
 use Swaggest\JsonSchema\Context;
 use Swaggest\JsonSchema\RemoteRef\BasicFetcher;
 use Swaggest\JsonSchema\RemoteRef\Preloaded;
@@ -116,7 +114,7 @@ protected static function setupGenOptions(Command\Definition $definition, $optio
             ->setDescription('Path to JSON schema file')->setIsUnnamed()->setIsRequired();
 
         $options->ptrInSchema = Command\Option::create()->setType()->setIsVariadic()
-            ->setDescription('JSON pointers to structure in in root schema, default #');
+            ->setDescription('JSON pointers to structure in root schema, default #');
 
         $options->defPtr = Command\Option::create()->setType()->setIsVariadic()
             ->setDescription('Definitions pointers to strip from symbol names, default #/definitions');
@@ -139,14 +137,20 @@ protected function loadSchema(&$skipRoot, &$baseName)
 
         $dataValue = $this->loadFile();
         $data = $dataValue;
-        
+
         if (!empty($this->ptrInSchema)) {
             $baseName = basename($this->schema);
             $skipRoot = true;
             $preloaded = new Preloaded();
             $preloaded->setSchemaData($baseName, $dataValue);
             $resolver->resolvers[] = $preloaded;
             $data = new \stdClass();
+
+            foreach ($this->defPtr as $defPtr) {
+                $this->defPtr[] = $baseName . $defPtr;
+            }
+            $this->defPtr[] = $baseName;
+
             foreach ($this->ptrInSchema as $i => $ptr) {
                 $data->oneOf[$i] = (object)[Schema::PROP_REF => $baseName . $ptr];
             }

src/Base.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace Swaggest\JsonCli;
+
+use Swaggest\JsonCli\GenPhp\BuilderOptions;
+use Swaggest\JsonSchema\Schema;
+use Swaggest\PhpCodeBuilder\JSDoc\TypeBuilder;
+use Yaoi\Command;
+
+class GenJSDoc extends Base
+{
+    use BuilderOptions;
+
+    /**
+     * @param Command\Definition $definition
+     * @param \stdClass|static $options
+     */
+    public static function setUpDefinition(Command\Definition $definition, $options)
+    {
+        $definition->description = 'Generate JSDoc code from JSON schema';
+        Base::setupGenOptions($definition, $options);
+    }
+
+
+    public function performAction()
+    {
+        try {
+            $skipRoot = false;
+            $baseName = null;
+            $schema = $this->loadSchema($skipRoot, $baseName);
+
+            $jb = new TypeBuilder();
+            $jb->trimNamePrefix = $this->defPtr;
+
+            if (!$schema instanceof Schema) {
+                $this->response->error('failed to assert Schema type, ' . get_class($schema) . ' received');
+                throw new ExitCode('', 1);
+            }
+
+            $jb->getTypeString($schema);
+
+            if ($this->output) {
+                if (!file_exists(dirname($this->output))) {
+                    $this->response->error('Destination directory does not exist, please create: ' . dirname($this->output));
+                    throw new ExitCode('', 1);
+                }
+                file_put_contents($this->output, $jb->file);
+
+            } else {
+                echo $jb->file;
+            }
+        } catch (\Exception $e) {
+            $this->response->error($e->getMessage());
+            throw new ExitCode('', 1);
+        }
+    }
+}