Modelina can be used in many different contexts and has many features, all depending on the output language. This document will walk you through you the library's basic usages.
For more advanced use-cases, please check out the advanced document.
For more specific integration options, please check out the integration document.
- Generator's options
- Understanding the output format
- Generate models from AsyncAPI documents
- Generate models from JSON Schema documents
- Generate models from Swagger 2.0 documents
- Generate models from OpenAPI documents
- Generate models from TypeScript type files
- Generate models from Meta models
- Generate Go models
- Generate C# models
- Generate Java models
- Generate TypeScript models
- Generate JavaScript models
- Generate Dart models
- Generate Rust models
- Generate Python models
- Generate Kotlin models
- Generate C++ (cplusplus) models
For Modelina, there exist 3 types of options for the generation process.
- Default options, are the default options the rest overwrite.
- Generator options, are used as the baseline options used for each model rendering, unless otherwise specified.
- Render options, are the last options to specify before the rendering of a model, this is used to specialize the options for individual rendering of a model.
Generator options are passed as the first argument to the generator's constructor. Check the example:
const generator = new TypeScriptGenerator({ ...options });Render options are passed as the first argument to the generator's render function. Check the example:
const generator = ...
generator.render(model, inputModel, { ...options });The output format is designed for you to use the generated models in further contexts. It might be part of a larger code generation such as AsyncAPI templates. This means that you can glue multiple models together into one large file, or split it out as you see fit.
All generate functions return an array of OutputModels, which contains the following properties.
| Property | Type | Description |
|---|---|---|
result |
String | The rendered content, that depends on whether you render it as a full model or partial model. |
model |
ConstrainedMetaModel | The constrained meta model that contains many other information about the rendered model. |
modelName |
String | The rendered name of the model. |
inputModel |
InputMetaModel |
Contains all the raw models along side the input they where generated for. Check the code for further information. |
dependencies |
String[] | List of rendered dependency imports that the model uses. |
When providing an AsyncAPI document, the library iterates the entire document and generate models for all defined message payloads. The message payloads are interpreted based on the schema format.
For JSON Schema it follows the JSON Schema input processing.
There are two ways to generate models for an AsyncAPI document.
- Generate from a parsed AsyncAPI 2.x document
- Generate from a parsed AsyncAPI 2.x document, from the old v1 parser
- Generate from an AsyncAPI 2.x JS object
The library expects the asyncapi property for the document to be set in order to understand the input format.
The message payloads, since it is a JSON Schema variant, is interpreted as a such.
These are the current known limitation of the AsyncAPI input.
Currently, only a limited number of schema formats are supported and we currently rely on the AsyncAPI parser to handle those schema formats and convert them into AsyncAPI Schema format. At some point in the future, Modelina will support all native schema formats, so it does not matter which standard you use to define the message payloads, you will be able to generate models from it.
Through the AsyncAPI 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. 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.
There are three ways to generate models for a JSON Schema document.
- Generate from a JSON Schema draft 7 JS object
- Generate from a JSON Schema draft 6 JS object
- Generate from a JSON Schema draft 4 JS object
The library expects the $schema property for the document to be set in order to understand the input format. By default, if no other inputs are detected, it defaults to JSON Schema draft 7. The process of interpreting a JSON Schema to a model can be read here.
There are one way to generate models from a Swagger 2.0 document.
The Swagger input processor expects that the property swagger is defined in order to know it should be processed.
The response payload and body parameters, since it is a JSON Schema variant, is interpreted as a such.
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. 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.
There are one way to generate models from an OpenAPI document
The OpenAPI input processor expects that the property openapi is defined in order to know it should be processed.
The response and request payloads, since it is a JSON Schema variant, is interpreted as a such.
These are the current known limitation of the OpenAPI inputs.
Through the OpenAPI 3.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. 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.
Currently, we support generating models from a TypeScript type file.
The TypeScript input processor expects that the typescript file and base directory where it's present, is passed as input, in order to process the types accurately. The input processor converts the TypeScript types into JSON Schema, which are then passed on to the JSON Schema processor.
Sometimes, the supported inputs such as AsyncAPI and JSON Schema wont be enough for your use-case and you want to create your own data models while still utilizing the full sweep of features from the generators.
You can do that by providing the internal meta model as input. Check out this example out for a live demonstration.
Check out this example out for a live demonstration.
Go is one of the many output languages we support. Check out this basic example for a live demonstration and the following Go documentation for more advanced use-cases.
C# is one of the many output languages we support. Check out this basic example for a live demonstration and the following C# documentation for more advanced use-cases.
Java is one of the many output languages we support. Check out this basic example for a live demonstration and the following Java documentation for more advanced use-cases.
TypeScript is one of the many output languages we support. Check out this basic example for a live demonstration and the following TypeScript documentation for more advanced use-cases.
JavaScript is one of the many output languages we support. Check out this basic example for a live demonstration and the following JavaScript documentation for more advanced use-cases.
Dart is one of the many output languages we support. Check out this basic example for a live demonstration and the following Dart documentation for more advanced use-cases.
Rust is one of the many output languages we support. Check out this basic example for a live demonstration and the following Rust documentation for more advanced use-cases.
Python is one of the many output languages we support. Check out this basic example for a live demonstration and the following Python documentation for more advanced use-cases.
Kotlin is one of the many output languages we support. Check out this basic example for a live demonstration as well as how to generate enums and the following Kotlin documentation for more advanced use-cases.
C++ is one of the many output languages we support. Check out this basic example for a live demonstration and the following C++ documentation for more advanced use-cases.