diff --git a/docs/advanced.md b/docs/advanced.md index 1e8955cf33..a5f0b58e2a 100644 --- a/docs/advanced.md +++ b/docs/advanced.md @@ -9,9 +9,6 @@ This document contains many of the advanced use-cases that you may stumble upon - [Generate models to separate files](#generate-models-to-separate-files) - [Include a custom function in the data model](#include-a-custom-function-in-the-data-model) - [Use the models for data transfer](#use-the-models-for-data-transfer) -- [Extend the logic of an existing renderer](#extend-the-logic-of-an-existing-renderer) -- [Build your own model renderer](#build-your-own-model-renderer) -- [Create your own models from the ground up, instead of a supported input](#create-your-own-models-from-the-ground-up-instead-of-a-supported-input) - [Adapting input and outputs](#adapting-input-and-outputs) - [Add logging to library](#add-logging-to-library) - [Change the generated indentation type and size](#change-the-generated-indentation-type-and-size) @@ -31,13 +28,6 @@ The reason for splitting the functionality is because in certain environments (l The file generators all follow the same pattern regardless of output language, which is the following format - `FileGenerator`. -Supported by: -- Java -- TypeScript -- C# -- Go -- JavaScript - > It is not supported in browsers. Check out this [example out for a live demonstration](../examples/generate-to-files). @@ -48,16 +38,15 @@ Sometimes you want to include custom functionality into the generated models, th Check out this [example out for a live demonstration](../examples/include-custom-function). ## Use the models for data transfer -TODO - -## Extend the logic of an existing renderer -TODO - -## Build your own model renderer -TODO - -## Create your own models from the ground up, instead of a supported input -TODO +One of the primary use-cases for the generated models, is to serialize and deserilize it to for example JSON, XML or binary. Each generator can have multiple ways to achieve this, and even support multiple libraries. This is achieved through presets, you can find them here for each output: + +- [C#](./languages/Csharp.md#generate-serializer-and-deserializer-functionality) +- [Dart](./languages/Dart.md#generate-serializer-and-deserializer-functionality) +- Go currently does not support this. +- [Java](./languages/Java.md#generate-serializer-and-deserializer-functionality) +- [JavaScript](./languages/JavaScript.md#generate-serializer-and-deserializer-functionality) +- [Rust](./languages/Rust.md) +- [TypeScript](./languages/TypeScript.md#generate-serializer-and-deserializer-functionality) ## Adapting input and outputs Sometimes you simply cannot make two things work together as you wished, maybe the input does not support it, or Modelina natively doesn't. However, because of the nature with presets, we can make it work anyway. diff --git a/docs/languages/Csharp.md b/docs/languages/Csharp.md index ef0c004226..3b4b12fb61 100644 --- a/docs/languages/Csharp.md +++ b/docs/languages/Csharp.md @@ -6,24 +6,47 @@ There are special use-cases that each language supports; this document pertains -- [Generate serializer and deserializer functionality](#generate-serializer-and-deserializer-functionality) -- [Generate models with equals and GetHashCode methods](#generate-models-with-equals-and-gethashcode-methods) -- [Generate models with auto-implemented properties](#generate-models-with-auto-implemented-properties) -- [Change the collection type for arrays](#change-the-collection-type-for-arrays) -- [Generate custom enum value names](#generate-custom-enum-value-names) -- [Generate models with inheritance](#generate-models-with-inheritance) + * [Generate serializer and deserializer functionality](#generate-serializer-and-deserializer-functionality) + + [To and from JSON](#to-and-from-json) + - [Using native System.Text.Json](#using-native-systemtextjson) + + [To and from XML](#to-and-from-xml) + + [To and from binary](#to-and-from-binary) + * [Generate models with equals and GetHashCode methods](#generate-models-with-equals-and-gethashcode-methods) + * [Generate models with auto-implemented properties](#generate-models-with-auto-implemented-properties) + * [Change the collection type for arrays](#change-the-collection-type-for-arrays) + * [Generate custom enum value names](#generate-custom-enum-value-names) + * [Generate models with inheritance](#generate-models-with-inheritance) +- [FAQ](#faq) + + [Why is the type `dynamic` or `dynamic[]` when it should be `X`?](#why-is-the-type-dynamic-or-dynamic-when-it-should-be-x) ## Generate serializer and deserializer functionality -Sometimes you want to serialize the data models into JSON. In order to do that use the preset `CSHARP_JSON_SERIALIZER_PRESET` +The most widely used usecase for Modelina is to generate models that include serilization and deserialization functionality to convert the models into payload data. This payload data can of course be many different kinds, JSON, XML, raw binary, you name it. -**External dependencies:** -Requires [System.Text.Json](https://devblogs.microsoft.com/dotnet/try-the-new-system-text-json-apis/), [System.Text.Json.Serialization](https://docs.microsoft.com/en-us/dotnet/standard/serialization/system-text-json-how-to?pivots=dotnet-6-0) and [System.Text.RegularExpressions](https://docs.microsoft.com/en-us/dotnet/api/system.text.regularexpressions?view=net-6.0) to work. +As you normally only need one library to do this, we developers can never get enough with creating new stuff, therefore there might be one specific library you need or want to integrate with. Therefore there is not one specific preset that offers everything. Below is a list of all the supported serialization presets. + +### To and from JSON +Here are all the supported presets and the libraries they use: + +- [Using native System.Text.Json](#using-native-systemtextjson) + +#### Using native System.Text.Json + +To include functionality that convert the models using the [System.Text.Json](https://devblogs.microsoft.com/dotnet/try-the-new-system-text-json-apis/), to use this, use the preset `CSHARP_JSON_SERIALIZER_PRESET`. Check out this [example for a live demonstration](../../examples/csharp-generate-serializer). +**External dependencies** +Requires [System.Text.Json](https://devblogs.microsoft.com/dotnet/try-the-new-system-text-json-apis/), [System.Text.Json.Serialization](https://docs.microsoft.com/en-us/dotnet/standard/serialization/system-text-json-how-to?pivots=dotnet-6-0) and [System.Text.RegularExpressions](https://docs.microsoft.com/en-us/dotnet/api/system.text.regularexpressions?view=net-6.0) to work. + +### To and from XML +Currently not supported, [let everyone know you need it](https://github.com/asyncapi/modelina/issues/new?assignees=&labels=enhancement&template=enhancement.md)! + +### To and from binary +Currently not supported, [let everyone know you need it](https://github.com/asyncapi/modelina/issues/new?assignees=&labels=enhancement&template=enhancement.md)! + ## Generate models with equals and GetHashCode methods To overwrite the `Equal` and `GetHashCode` methods, use the preset `CSHARP_COMMON_PRESET` and provide the options `equal: true` and `hashCode: true` @@ -53,4 +76,10 @@ Check out this [example for a live demonstration](../../examples/csharp-overwrit If you want the generated models to inherit from a custom class, you can overwrite the existing rendering behavior and create your own class setup. Check out this [example for a live demonstration](../../examples/csharp-use-inheritance). +# FAQ +This is the most asked questions and answers which should be your GOTO list to check before asking anywhere else. Cause it might already have been answered! + +### Why is the type `dynamic` or `dynamic[]` when it should be `X`? +Often times you might encounter variables which as of type `dynamic` or `dynamic[]`, which is our fallback type when we cannot accurately find the right type. +**If you are encountering this when your input is JSON Schema/OpenAPI/AsyncAPI**, it most likely is because of a property being defined as having multiple types as a union, which the C# generator cannot natively handle and fallback to `dynamic`. For arrays, you have to remember that `additionalItems` is by default `true`, this means that even though you use `items: { type: "string"}` by not setting `additionalItems: false`, it's the same as setting `items: { type: ["array", "boolean", "integer", "null", "number", "object", "string"]}`. \ No newline at end of file diff --git a/docs/languages/Dart.md b/docs/languages/Dart.md index 1d2f1ded6b..5c7e5406d3 100644 --- a/docs/languages/Dart.md +++ b/docs/languages/Dart.md @@ -5,12 +5,33 @@ There are special use-cases that each language supports; this document pertains -- [Include json_annotation for the class and enums](#include-json-annotation-for-the-class) +- [Generate serializer and deserializer functionality](#generate-serializer-and-deserializer-functionality) + * [To and from JSON](#to-and-from-json) + + [JSON annotation](#json-annotation) + * [To and from XML](#to-and-from-xml) + * [To and from binary](#to-and-from-binary) -## Include Json annotation for the class and enums +## Generate serializer and deserializer functionality -When you generate the models with json annotation, generated files include json_annotation package (https://pub.dev/packages/json_annotation/) and their syntax +The most widely used usecase for Modelina is to generate models that include serilization and deserialization functionality to convert the models into payload data. This payload data can of course be many different kinds, JSON, XML, raw binary, you name it. + +As you normally only need one library to do this, we developers can never get enough with creating new stuff, therefore there might be one specific library you need or want to integrate with. Therefore there is not one specific preset that offers everything. Below is a list of all the supported serialization presets. + +### To and from JSON +Here are all the supported presets and the libraries they use: + +- [JSON annotation](#json-annotation) + +#### JSON annotation + +When you generate the models with json annotation, generated files include json_annotation package (https://pub.dev/packages/json_annotation/) and their syntax. Check out this [example for a live demonstration](../../examples/dart-generate-json-annotation). + +### To and from XML +Currently not supported, [let everyone know you need it](https://github.com/asyncapi/modelina/issues/new?assignees=&labels=enhancement&template=enhancement.md)! + +### To and from binary +Currently not supported, [let everyone know you need it](https://github.com/asyncapi/modelina/issues/new?assignees=&labels=enhancement&template=enhancement.md)! diff --git a/docs/languages/Java.md b/docs/languages/Java.md index 3c262fb26d..f8745ec24d 100644 --- a/docs/languages/Java.md +++ b/docs/languages/Java.md @@ -12,8 +12,12 @@ There are special use-cases that each language supports; this document pertains - [Include toString function for the class](#include-tostring-function-for-the-class) - [Include JavaDoc for properties](#include-javadoc-for-properties) - [Include Javax validation constraint annotations for properties](#include-javax-validation-constraint-annotations-for-properties) -- [Include Jackson annotations for the class](#include-jackson-annotations-for-the-class) -- [Include JSON marshaling and unmarshaling methods](#include-json-marshaling-and-unmarshaling-methods) +- [Generate serializer and deserializer functionality](#generate-serializer-and-deserializer-functionality) + * [To and from JSON](#to-and-from-json) + + [Jackson annotation](#jackson-annotation) + + [JSON marshaling and unmarshaling methods](#json-marshaling-and-unmarshaling-methods) + * [To and from XML](#to-and-from-xml) + * [To and from binary](#to-and-from-binary) @@ -53,17 +57,38 @@ In some cases, when you generate the models from JSON Schema, you may want to in Check out this [example for a live demonstration](../../examples/java-generate-javax-constraint-annotation). -## Include Jackson annotations for the class +## Generate serializer and deserializer functionality + +The most widely used usecase for Modelina is to generate models that include serilization and deserialization functionality to convert the models into payload data. This payload data can of course be many different kinds, JSON, XML, raw binary, you name it. + +As you normally only need one library to do this, we developers can never get enough with creating new stuff, therefore there might be one specific library you need or want to integrate with. Therefore there is not one specific preset that offers everything. Below is a list of all the supported serialization presets. + +### To and from JSON +Here are all the supported presets and the libraries they use: + +- [Jackson annotation](#jackson-annotation) +- [JSON marshaling and unmarshaling methods](#json-marshaling-and-unmarshaling-methods) + +#### Jackson annotation To generate Java data models with Jackson annotation using `JAVA_JACKSON_PRESET` option. Check out this [example for a live demonstration](../../examples/java-generate-jackson-annotation). -## Include JSON marshaling and unmarshaling methods +**External dependencies** +Requires [com.fasterxml.jackson.annotation](https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-annotations) to work. + +#### JSON marshaling and unmarshaling methods Sometimes you just want to convert your class to JSON without the use of annotations such as Jackson. Check out this [example for a live demonstration](../../examples/java-generate-marshalling). -External dependencies -- Requires [org.json package](https://search.maven.org/artifact/org.json/json/20211205/bundle) to work +**External dependencies** +Requires [org.json package](https://search.maven.org/artifact/org.json/json/20211205/bundle) to work. + +### To and from XML +Currently not supported, [let everyone know you need it](https://github.com/asyncapi/modelina/issues/new?assignees=&labels=enhancement&template=enhancement.md)! + +### To and from binary +Currently not supported, [let everyone know you need it](https://github.com/asyncapi/modelina/issues/new?assignees=&labels=enhancement&template=enhancement.md)! diff --git a/docs/languages/JavaScript.md b/docs/languages/JavaScript.md index 770ec6137f..5b918724dd 100644 --- a/docs/languages/JavaScript.md +++ b/docs/languages/JavaScript.md @@ -6,7 +6,11 @@ There are special use-cases that each language supports; this document pertains - [Rendering complete models to a specific module system](#rendering-complete-models-to-a-specific-module-system) -- [Generate un/marshal functions for classes](#generate-unmarshal-functions-for-classes) +- [Generate serializer and deserializer functionality](#generate-serializer-and-deserializer-functionality) + * [To and from JSON](#to-and-from-json) + + [Generate marshalling and unmarshalling functions](#generate-marshalling-and-unmarshalling-functions) + * [To and from XML](#to-and-from-xml) + * [To and from binary](#to-and-from-binary) - [Generate example data function](#generate-example-data-function) @@ -18,15 +22,30 @@ Check out this [example for a live demonstration how to generate the complete Ja Check out this [example for a live demonstration how to generate the complete JavaScript models to use CJS module system](../../examples/javascript-use-cjs). +## Generate serializer and deserializer functionality -## Generate un/marshal functions for classes +The most widely used usecase for Modelina is to generate models that include serilization and deserialization functionality to convert the models into payload data. This payload data can of course be many different kinds, JSON, XML, raw binary, you name it. -Sometimes you want to use the models for data transfers, and while most cases would work out of the box, custom serializer functionality is needed for the advanced cases. If you generated the data models based on a JSON Schema document and you want the serialized data to validate against the schema, this functionality is REQUIRED. +As you normally only need one library to do this, we developers can never get enough with creating new stuff, therefore there might be one specific library you need or want to integrate with. Therefore there is not one specific preset that offers everything. Below is a list of all the supported serialization presets. + +### To and from JSON +Here are all the supported presets and the libraries they use: + +- [Generate marshalling and unmarshalling functions](#generate-marshalling-and-unmarshalling-functions) + +#### Generate marshalling and unmarshalling functions + +Using the preset `JS_COMMON_PRESET` with the option `marshalling` to `true`, renders two function for the class models. One which convert the model to JSON and another which convert the model from JSON to an instance of the class. -Here, this can be done by including the preset `JS_COMMON_PRESET` using the option `marshalling`. Check out this [example out for a live demonstration](../../examples/javascript-generate-marshalling). +### To and from XML +Currently not supported, [let everyone know you need it](https://github.com/asyncapi/modelina/issues/new?assignees=&labels=enhancement&template=enhancement.md)! + +### To and from binary +Currently not supported, [let everyone know you need it](https://github.com/asyncapi/modelina/issues/new?assignees=&labels=enhancement&template=enhancement.md)! + ## Generate example data function Generate example instance of the data model including the preset `JS_COMMON_PRESET` using the option `example`. diff --git a/docs/languages/TypeScript.md b/docs/languages/TypeScript.md index df2b1e46b0..95941f4ba8 100644 --- a/docs/languages/TypeScript.md +++ b/docs/languages/TypeScript.md @@ -8,7 +8,11 @@ There are special use-cases that each language supports; this document pertains - [Generate an interface instead of classes](#generate-an-interface-instead-of-classes) - [Generate union types instead of enums](#generate-union-types-instead-of-enums) -- [Generate un/marshal functions for classes](#generate-unmarshal-functions-for-classes) +- [Generate serializer and deserializer functionality](#generate-serializer-and-deserializer-functionality) + * [To and from JSON](#to-and-from-json) + + [Generate marshalling and unmarshalling functions](#generate-marshalling-and-unmarshalling-functions) + * [To and from XML](#to-and-from-xml) + * [To and from binary](#to-and-from-binary) - [Generate example data function](#generate-example-data-function) - [Rendering complete models to a specific module system](#rendering-complete-models-to-a-specific-module-system) - [Rendering comments from description and example fields](#rendering-comments-from-description-and-example-fields) @@ -37,14 +41,30 @@ export type Event = "ping" | "pong"; Check out this [example out for a live demonstration](../../examples/typescript-enum-type). -## Generate un/marshal functions for classes +## Generate serializer and deserializer functionality -Sometimes you want to use the models for data transfers, and while most cases would work out of the box, custom serializer functionality is needed for the advanced cases. If you generated the data models based on a JSON Schema document and you want the serialized data to validate against the schema, this functionality is REQUIRED. +The most widely used usecase for Modelina is to generate models that include serilization and deserialization functionality to convert the models into payload data. This payload data can of course be many different kinds, JSON, XML, raw binary, you name it. -This can be done by including the preset `TS_COMMON_PRESET` using the option `marshalling`. +As you normally only need one library to do this, we developers can never get enough with creating new stuff, therefore there might be one specific library you need or want to integrate with. Therefore there is not one specific preset that offers everything. Below is a list of all the supported serialization presets. + +### To and from JSON +Here are all the supported presets and the libraries they use: + +- [Generate marshalling and unmarshalling functions](#generate-marshalling-and-unmarshalling-functions) + +#### Generate marshalling and unmarshalling functions + +Using the preset `TS_COMMON_PRESET` with the option `marshalling` to `true`, renders two function for the class models. One which convert the model to JSON and another which convert the model from JSON to an instance of the class. Check out this [example out for a live demonstration](../../examples/typescript-generate-marshalling). +### To and from XML +Currently not supported, [let everyone know you need it](https://github.com/asyncapi/modelina/issues/new?assignees=&labels=enhancement&template=enhancement.md)! + +### To and from binary +Currently not supported, [let everyone know you need it](https://github.com/asyncapi/modelina/issues/new?assignees=&labels=enhancement&template=enhancement.md)! + + ## Generate example data function You might stumble upon a user case (we had one in code generation) where you want a simple example instance of the generated data model. diff --git a/package.json b/package.json index 4d79234f2b..1ab6117453 100644 --- a/package.json +++ b/package.json @@ -82,7 +82,7 @@ "lint": "eslint --max-warnings 0 --config .eslintrc .", "lint:fix": "eslint --max-warnings 0 --config .eslintrc . --fix", "release": "semantic-release", - "generate:readme:toc": "markdown-toc -i README.md && markdown-toc -i ./docs/usage.md && markdown-toc -i ./docs/integration.md && markdown-toc -i ./docs/advanced.md && markdown-toc -i ./docs/languages/TypeScript.md && markdown-toc -i ./docs/languages/Java.md && markdown-toc -i ./docs/languages/JavaScript.md && markdown-toc -i ./docs/languages/Csharp.md && markdown-toc -i ./docs/README.md && markdown-toc -i ./docs/generators.md", + "generate:readme:toc": "markdown-toc -i README.md && markdown-toc -i ./docs/usage.md && markdown-toc -i ./docs/integration.md && markdown-toc -i ./docs/advanced.md && markdown-toc -i ./docs/languages/Dart.md && markdown-toc -i ./docs/languages/TypeScript.md && markdown-toc -i ./docs/languages/Java.md && markdown-toc -i ./docs/languages/JavaScript.md && markdown-toc -i ./docs/languages/Csharp.md && markdown-toc -i ./docs/README.md && markdown-toc -i ./docs/generators.md", "generate:assets": "npm run build:prod && npm run docs && npm run generate:readme:toc", "bump:version": "npm --no-git-tag-version --allow-same-version version $VERSION", "prepublishOnly": "npm run build:prod && npm run generate:readme:toc"