Skip to content

Latest commit

 

History

History
210 lines (129 loc) · 12.4 KB

usage.md

File metadata and controls

210 lines (129 loc) · 12.4 KB

Usages

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

For Modelina, there exist 3 types of options for the generation process.

  1. Default options, are the default options the rest overwrite.
  2. Generator options, are used as the baseline options used for each model rendering, unless otherwise specified.
  3. 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 });

Understanding the output format

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.

Generate models from AsyncAPI documents

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.

The message payloads, regardless of schemaFormat, are converted to a JSON Schema variant and is interpreted as a such.

Limitations and Compatibility

These are the current known limitation of the AsyncAPI input.

Polymorphism

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 opinion here.

Generate models from JSON Schema documents

There are three ways to generate models for a JSON Schema document.

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.

Generate models from Swagger 2.0 documents

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.

Limitations and Compatibility

These are the current known limitation of the Swagger 2.0 input.

Polymorphism

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 opinion here.

Generate models from OpenAPI documents

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.

Limitations and Compatibility

These are the current known limitation of the OpenAPI inputs.

Polymorphism

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 opinion here.

Generate models from TypeScript type files

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.

Generate models from Meta models

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.

Generate Go models

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.

Generate C# models

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.

Generate Java models

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.

Generate TypeScript models

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.

Generate JavaScript models

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.

Generate Dart models

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.

Generate Rust models

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.

Generate Python models

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.

Generate Kotlin models

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.

Generate C++ (cplusplus) models

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.

Generate PHP models

PHP is one of the many output languages we support. Check out this basic example for a live demonstration and the following PHP documentation for more advanced use-cases.

Generate Scala models

Scala is one of the many output languages we support. Check out this basic example for a live demonstration and the following Scala documentation for more advanced use-cases.