diff --git a/README.md b/README.md index acfe5e9928..986614fc60 100644 --- a/README.md +++ b/README.md @@ -200,7 +200,7 @@ The following table provides a short summary of available features for supported We support the following JSON Schema versions: Draft-4, Draft-6 and Draft-7 - OpenAPI + OpenAPI We support the following OpenAPI versions: Swagger 2.0 and OpenAPI 3.0, which generates models for all the defined request and response payloads. diff --git a/docs/README.md b/docs/README.md index 83b34f3286..5b194699bd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -63,13 +63,15 @@ No one wants to read the code to find information about it, instead use the [/ap ### Languages Each language has its own limitations, corner cases, and features; thus, each language has separate documentation. +- [C++](./languages/Cplusplus.md) - [C#](./languages/Csharp.md) - [Dart](./languages/Dart.md) - [Go](./languages/Go.md) - [Java](./languages/Java.md) - [JavaScript](./languages/JavaScript.md) -- [Rust](./languages/Rust.md) +- [Kotlin](./languages/Kotlin.md) +- [PHP](./languages/Php.md) - [Python](./languages/Python.md) +- [Rust](./languages/Rust.md) +- [Scala](./languages/Scala.md) - [TypeScript](./languages/TypeScript.md) -- [Kotlin](./languages/Kotlin.md) -- [C++](./languages/Cplusplus.md) diff --git a/docs/advanced.md b/docs/advanced.md index c94b68aeba..c15cf124f8 100644 --- a/docs/advanced.md +++ b/docs/advanced.md @@ -47,12 +47,17 @@ Check out this [example out for a live demonstration](../examples/include-custom 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/Cplusplus.md#generate-serializer-and-deserializer-functionality) - [C#](./languages/Csharp.md#generate-serializer-and-deserializer-functionality) - [Dart](./languages/Dart.md#generate-serializer-and-deserializer-functionality) -- Go currently does not support this. +- [Go](./languages/Go.md#generate-serializer-and-deserializer-functionality) - [Java](./languages/Java.md#generate-serializer-and-deserializer-functionality) - [JavaScript](./languages/JavaScript.md#generate-serializer-and-deserializer-functionality) +- [Kotlin](./languages/Kotlin.md#generate-serializer-and-deserializer-functionality) +- [PHP](./languages/Php.md#generate-serializer-and-deserializer-functionality) +- [Python](./languages/Python.md#generate-serializer-and-deserializer-functionality) - [Rust](./languages/Rust.md) +- [Scala](./languages/Scala.md#generate-serializer-and-deserializer-functionality) - [TypeScript](./languages/TypeScript.md#generate-serializer-and-deserializer-functionality) ## Adapting input and outputs diff --git a/docs/constraints/README.md b/docs/constraints/README.md index 5d52fc4841..7db869a3b8 100644 --- a/docs/constraints/README.md +++ b/docs/constraints/README.md @@ -16,14 +16,18 @@ class 1name {} There are many rules as such, but to get the full description about the default constraints here: +- [C++](./constraints/Csplusplus.md) - [C#](./constraints/CSharp.md) - [Dart](./constraints/Dart.md) - [Go](./constraints/Go.md) - [Java](./constraints/Java.md) - [JavaScript](./constraints/JavaScript.md) +- [Kotlin](./constraints/Kotlin.md) +- [PHP](./constraints/PHP.md) +- [Python](./constraints/Python.md) - [Rust](./constraints/Rust.md) +- [Scala](./constraints/Scala.md) - [TypeScript](./constraints/TypeScript.md) -- [Python](./constraints/Python.md) Even though there are many of these constraints, there might be reasons you want to customize the behavior to make it suit your use-case. Therefore each of the constraint rules can be overwritten completely and allow for you to implement your own behavior. diff --git a/docs/languages/Cplusplus.md b/docs/languages/Cplusplus.md index a3f08057b1..ce51094a89 100644 --- a/docs/languages/Cplusplus.md +++ b/docs/languages/Cplusplus.md @@ -1,10 +1,6 @@ # C++ There are special use-cases that each language supports; this document pertains to **C++ models**. -Limitations: -- We use v17 of C++ as our baseline. -- Circular models are not supported. - @@ -16,6 +12,10 @@ Limitations: +Current limitations of C++: +- We use v17 of C++ as our baseline. +- Circular models are not supported. + ## Generate serializer and deserializer functionality The most widely used usecase for Modelina is to generate models that include serialization 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. diff --git a/docs/languages/Csharp.md b/docs/languages/Csharp.md index 7015ff91bd..965735b8c1 100644 --- a/docs/languages/Csharp.md +++ b/docs/languages/Csharp.md @@ -87,11 +87,14 @@ 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-generate-json-serializer). + + ## Generate models as records Since C# 9 the language now supports records as an alternative to classes suitable for roles like DTO's. Modelina can generate records by setting the `modelType: record` option. Note that this renderer does not support the `autoImplementedProperties` option as this is default with records. -Check out this [example for a live demonstration](../../examples/csharp-generate-records). +Check out this [example for a live demonstration](../../examples/csharp-use-inheritance). ## Generate code that handles nullable mode @@ -106,4 +109,4 @@ This is the most asked questions and answers which should be your GOTO list to c ### 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 +**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`. \ No newline at end of file diff --git a/docs/languages/Go.md b/docs/languages/Go.md index 7b15f3e5d3..7cfa209ce8 100644 --- a/docs/languages/Go.md +++ b/docs/languages/Go.md @@ -1,4 +1,27 @@ # Go There are special use-cases that each language supports; this document pertains to **Go models**. -At the moment, Go models have no specific features. + + + +- [Generate serializer and deserializer functionality](#generate-serializer-and-deserializer-functionality) + * [To and from JSON](#to-and-from-json) + * [To and from XML](#to-and-from-xml) + * [To and from binary](#to-and-from-binary) + + + +## Generate serializer and deserializer functionality + +The most widely used usecase for Modelina is to generate models that include serialization 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 +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 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/Kotlin.md b/docs/languages/Kotlin.md index 57fcbc66b0..093acb12ae 100644 --- a/docs/languages/Kotlin.md +++ b/docs/languages/Kotlin.md @@ -1,11 +1,11 @@ # Kotlin -There are special use-cases that each language supports; this document pertains to **Kotlin models**. +There are special use cases that each language supports; this document pertains to **Kotlin models**. -Since `data classes` are used for every model that has got properties, there is no need for additional settings or +Since `data classes` are used for every model that has properties, there is no need for additional settings or features to generate `toString()`, `equals()`, `hashCode()`, getters or setters. -Classes without properties are depicted by usual `classes`, they get no `toString()`, `equals()` or `hashCode()` +Classes without properties are depicted by usual `classes`, they get no `toString()`, `equals()`, or `hashCode()` implementation. The default one should suffice here. @@ -28,7 +28,7 @@ Check out this [example for a live demonstration](../../examples/kotlin-generate ## Change the collection type for arrays -Sometimes, we might want to render a different collection type, and instead of the default `Array` use as `List` type. To do so, provide the option `collectionType: 'List'`. +Sometimes, we might want to render a different collection type, and instead of the default `Array` use it as a `List` type. To do so, provide the option `collectionType: 'List'`. Check out this [example for a live demonstration](../../examples/kotlin-change-collection-type). @@ -40,13 +40,15 @@ Check out this [example for a live demonstration](../../examples/kotlin-generate ## Generate serializer and deserializer functionality -The most widely used usecase for Modelina is to generate models that include serialization and deserialization functionality to convert the models into payload data. This payload data can of course be many kinds, JSON, XML, raw binary, you name it. +The most widely used use case for Modelina is to generate models that include serialization and deserialization functionality to convert the models into payload data. This payload data can of course be many 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 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 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/Php.md b/docs/languages/Php.md index d69b3b5fa4..1c7b6a739c 100644 --- a/docs/languages/Php.md +++ b/docs/languages/Php.md @@ -8,6 +8,7 @@ There are special use-cases that each language supports; this document pertains - [Description Present](#description-present) - [Generate serializer and deserializer functionality](#generate-serializer-and-deserializer-functionality) * [To and from JSON](#to-and-from-json) + + [Generate json_encode function](#generate-json_encode-function) * [To and from XML](#to-and-from-xml) * [To and from binary](#to-and-from-binary) @@ -29,6 +30,12 @@ Therefore, there is not one specific preset that offers everything. Below is a l ### To and from JSON +Here are all the supported presets and the libraries they use for converting to and from JSON: + +- [Generate json_encode function](#generate-json_encode-function) + +#### Generate json_encode function + Objects in PHP can generally be serialized to JSON using the [`json_encode()` function](https://www.php.net/manual/en/function.json-encode.php). To ensure that the data is serialized correctly, the [`JsonSerializable` interface](https://www.php.net/manual/en/class.jsonserializable.php) needs to be implemented. This will ensure that, for example, enum values and property names are serialized correctly. diff --git a/docs/languages/Scala.md b/docs/languages/Scala.md index 249be7b0df..01c893474b 100644 --- a/docs/languages/Scala.md +++ b/docs/languages/Scala.md @@ -18,7 +18,7 @@ There are special use-cases that each language supports; this document pertains By default, descriptions are not rendered for the model; you can change that by applying `SCALA_DESCRIPTION_PRESET`. -Check out this [example for a live demonstration](../../examples/php-generate-documentation-preset). +Check out this [example for a live demonstration](../../examples/scala-generate-documentation). ## Generate serializer and deserializer functionality diff --git a/docs/usage.md b/docs/usage.md index 4862187807..d0699d77ec 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -124,7 +124,7 @@ These are the current known limitation of the Swagger 2.0 input. Through the Swagger 2.0 Schema you are able to use `discriminator` for achieving polymorphism. Current version of Modelina does not generate the expected inheritance of models, instead it's current behavior is to [merge the schemas together](./inputs/JSON_Schema.md#processing-sub-schemas). This means you will still get access to the properties that missing inherited model has, but without the inheritance. -Long term if this is something you wish was supported, voice your [opionion here](https://github.com/asyncapi/modelina/issues/108). +Long term if this is something you wish was supported, voice your [opinion here](https://github.com/asyncapi/modelina/issues/108). ## Generate models from OpenAPI documents diff --git a/modelina-website/scripts/build-docs.js b/modelina-website/scripts/build-docs.js index c434dcea43..55b44803f1 100644 --- a/modelina-website/scripts/build-docs.js +++ b/modelina-website/scripts/build-docs.js @@ -23,7 +23,9 @@ function prepareContent(content) { // Use correct example links content = content.replace(/\]\((.*?)examples\/(.*?)\/?\)/g, '](/examples?selectedExample=$2)'); - + content = content.replace('/examples?selectedExample=integrate-with-react', 'https://github.com/asyncapi/modelina/tree/master/examples/integrate-with-react'); + content = content.replace('/examples?selectedExample=integrate-with-next', 'https://github.com/asyncapi/modelina/tree/master/examples/integrate-with-next'); + content = content.replace('/examples?selectedExample=integrate-with-maven', 'https://github.com/asyncapi/modelina/tree/master/examples/integrate-with-maven'); // Replace all references to local images for docs content = content.replace(/"(.*?)\/img\/(.*?)"/g, '"/img/docs/img/$2"');