Add support for comments and annotations

asyncapi · Jan 29, 2024 · 9347cd0 · 9347cd0
1 parent 02a8dfd
commit 9347cd0
Show file tree

Hide file tree

Showing 15 changed files with 14,402 additions and 14,175 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,9 +1,10 @@
-node_modules
-*.tgz
-.vscode
-.DS_Store
-/docs
-/coverage
-/lib
-/esm
-/cjs
+node_modules
+*.tgz
+.vscode
+.DS_Store
+.idea
+/docs
+/coverage
+/lib
+/esm
+/cjs
diff --git a/README.md b/README.md
@@ -1,15 +1,15 @@
 # ProtoBuff Data Types Schema Parser
 
 A schema parser for Protocol Buffers data types.
-For ProtoBuff 2 and 3 schemas.  
+For ProtoBuff 2 and 3 schemas.
 
-There is no explicit distinction between ProtoBuff 2 and 3. You dont have to expect any errors if your `schemaFormat` is `application/vnd.google.protobuf;version=2` defined, but your schema is proto3. 
+There is no explicit distinction between ProtoBuff 2 and 3. You dont have to expect any errors if your `schemaFormat`
+is `application/vnd.google.protobuf;version=2` defined, but your schema is proto3.
 
 Version >= `2.0.0` of package is only supported by `@asyncapi/parser` version >= `2.0.0`.
 
 This package is browser-compatible.
 
-
 ## Installation
 
 ```
@@ -21,11 +21,11 @@ yarn add @asyncapi/protobuf-schema-parser
 ## Usage
 
 ```ts
-import { Parser } from '@asyncapi/parser';
-import { ProtoSchemaParser } from '@asyncapi/protobuf-schema-parser'
+import {Parser} from '@asyncapi/parser';
+import {ProtoSchemaParser} from '@asyncapi/protobuf-schema-parser'
 
 const parser = new Parser();
-parser.registerSchemaParser(ProtoSchemaParser()); 
+parser.registerSchemaParser(ProtoSchemaParser());
 
 const asyncapiWithProto = `
 asyncapi: 2.0.0
@@ -51,15 +51,15 @@ channels:
             }
 `
 
-const { document } = await parser.parse(asyncapiWithProto);
+const {document} = await parser.parse(asyncapiWithProto);
 ```
 
 ```js
-const { Parser } = require('@asyncapi/parser');
-const { ProtoSchemaParser } = require('@asyncapi/protobuf-schema-parser');
+const {Parser} = require('@asyncapi/parser');
+const {ProtoSchemaParser} = require('@asyncapi/protobuf-schema-parser');
 
 const parser = new Parser();
-parser.registerSchemaParser(ProtoSchemaParser()); 
+parser.registerSchemaParser(ProtoSchemaParser());
 
 const asyncapiWithProto = `
 asyncapi: 2.0.0
@@ -85,14 +85,67 @@ channels:
             }
 `
 
-const { document } = await parser.parse(asyncapiWithProto);
+const {document} = await parser.parse(asyncapiWithProto);
 ```
 
 Place your protoBuff schema as string in `payload` to get it parsed.
 
-Refferences are NOT supported:
+References are NOT supported:
+
 - no support for `$ref`
-- no support for [`import`](https://protobuf.dev/programming-guides/proto3/#importing-definitions), except the default google types:
-  - google/protobuf/*
-  - google/type/*
+- no support for [`import`](https://protobuf.dev/programming-guides/proto3/#importing-definitions), except the default
+  google types:
+    - google/protobuf/*
+    - google/type/*
+
+## Comments
+
+Each field of a message may have a comment witch will be reflected as json schema `description`.
+Furthermore, the comment can contain the following annotations:
+
+```
+message Point {
+    /*
+     * The cordinate on the x axis.
+     * @Default 99
+     * @Min 0
+     * @Max 100 
+     */
+    required int32 x = 1;
+    
+    /*
+     * The cordinate on the y axis.
+     * @Default 12
+     * @Min 0
+     * @Max 100 
+     */
+    required int32 y = 2;
+    optional string label = 3;
+}
+```
+
+### Per field annotation
+
+| annotation         	 | description 	                                                                                                      |
+|----------------------|:-------------------------------------------------------------------------------------------------------------------|
+| @Example  	          | json schema examples keyword. Can exists multiple times.	                                                          |
+| @Min or @Minimum     | json schema [numeric validator](https://json-schema.org/understanding-json-schema/reference/numeric#range)	        |
+| @Max or @Maximum     | json schema [numeric validator](https://json-schema.org/understanding-json-schema/reference/numeric#range)         |
+| @Pattern             | json scheme [string validator](https://json-schema.org/understanding-json-schema/reference/string#regexp)	         |
+| @ExclusiveMinimum    | json schema [numeric validator](https://json-schema.org/understanding-json-schema/reference/numeric#range)         |
+| @ExclusiveMaximum    | json schema [numeric validator](https://json-schema.org/understanding-json-schema/reference/numeric#range)	        |
+| @MultipleOf          | json schema [numeric validator](https://json-schema.org/understanding-json-schema/reference/numeric#multiples)   	 |
+| @MinLength           | json scheme [string validator](https://json-schema.org/understanding-json-schema/reference/string#length)          |
+| @MaxLength           | json scheme [string validator](https://json-schema.org/understanding-json-schema/reference/string#length)          |
+| @MinItems            | json scheme [array validator](https://json-schema.org/understanding-json-schema/reference/array#length)	           |
+| @MaxItems            | json scheme [array validator](https://json-schema.org/understanding-json-schema/reference/array#length)		          |
+| @Default             | json schema [default value](https://opis.io/json-schema/1.x/default-value.html)	                                   |
+
+### Per message annotation
+
+
+| annotation | description 	                                                                                            |
+|------------|:---------------------------------------------------------------------------------------------------------|
+| @RootNode  | If there are multiple types without an parent you can give a hint to the root node with this annotation. |
+