@asyncapi/modelina v3.8.0

Your one-stop tool for generating accurate and well-tested models for representing the message payloads. Use it as a tool in your development workflow, or a library in a larger integrations, entirely in your control.

• Installing Modelina
• AsyncAPI CLI
• Features
• Requirements
• Documentation
• Examples
• Versioning and maintenance
• Development
• Contributing
• Contributors

Installing Modelina

Run this command to install Modelina in your project:

npm install @asyncapi/modelina

AsyncAPI CLI

If you have the AsyncAPI CLI installed (ONLY support AsyncAPI inputs), you can run the following command to use Modelina:

asyncapi generate models <language> ./asyncapi.json

const asyncapi = ...
const jsonschema = ...
const openapi = ... 
const metamodel = ... 
...
const models = await generator.generate(
  asyncapi | jsonschema | openapi | metamodel
);

const generator = new TypeScriptGenerator();
const generator = new CsharpGenerator();
const generator = new JavaGenerator();
const generator = new RustGenerator();
...
const models = await generator.generate(input);

• Want to show the generated models on a website? Sure!
• Want to generate the models into files? Sure!
• Want to combine all the models into one single file? Sure!

Whatever interaction you need, you can create.

const models = await generator.generate(input);
for (const model in models) { 
  const generatedCode = model.result;
  const dependencies = model.dependencies;
  const modeltype = model.type;
  const modelName = model.modelName;
  ...
}

const generator = new TypeScriptGenerator({
  constraints: {
    modelName: ({modelName}) => {
      // Implement your own constraining logic
      return modelName;
    }
  }
});

const generator = new TypeScriptGenerator({
  presets: [
    {
      class: {
        additionalContent({ content }) {
          return `${content}
public myCustomFunction(): string {
  return 'A custom function for each class';
}`;
        },
      }
    }
  ]
});
const models = await generator.generate(input);

const myCustomFunction1 = {
  class: {
    additionalContent({ content }) {
      return `${content}
public myCustomFunction(): string {
return 'A custom function for each class';
}`;
    },
  }
};
const myCustomFunction2 = {...};
const generator = new TypeScriptGenerator({
  presets: [
    myCustomFunction1,
    myCustomFunction2
  ]
});
const models = await generator.generate(input);

Features

The following table provides a short summary of available features for supported output languages. To see the complete feature list for each language, please click the individual links for each language.

Requirements

The following are a requirement in order to use Modelina.

• NodeJS >= 18

Documentation

A feature in Modelina cannot exists without an example and documentation for it. You can find all the documentation here.

Examples

Do you need to know how to use the library in certain scenarios?

We have gathered all the examples in a separate folder and they can be found under the examples folder.

Versioning and maintenance

As of version 1, Modelina has a very strict set of changes we are allowed to do before it requires a major version change. In short, any changes that change the generated outcome are not allowed as it's a breaking change for the consumer of the generated models.

Here is a list of changes we are allowed to do that would not require a breaking change:

• Adding new features (that do not change existing output), such as generators, presets, input processors, etc.
• Change existing features, by providing options that default to current behavior. This could be a preset that adapts the output based on options, as long as the API of Modelina and the API of the generated models does not have any breaking changes.
• Bug fixes where the generated code is otherwise unusable (syntax errors, etc).

Breaking changes are allowed and expected at a frequent rate, of course where it makes sense we will try to bundle multiple changes together.

We of course will do our best to uphold this, but mistakes can happen, and if you notice any breaking changes please let us know!

Because of the number of the limited number of champions, only the most recent major version will be maintained.

Major versions are currently happening at a 3-month cadence (in a similar fashion as the AsyncAPI specification), this will happen in January, April, June, and September.

Development

We try to make it as easy for you as possible to set up your development environment to contribute to Modelina. You can find the development documentation here.

Contributing

Without contributions, Modelina would not exist, it's a community project we build together to create the best possible building blocks, and we do this through champions.

We have made quite a comprehensive contribution guide to give you a lending hand in how different features and changes are introduced.

If no documentation helps you, here is how you can reach out to get help:

• On the official AsycnAPI slack under the #04_tooling channel
• Tag a specific CODEOWNER in your PR
• Generally, it's always a good idea to do everything in public, but in some cases, it might not be possible. In those circumstances you can contact the following:
  • jonaslagoni (on AsyncAPI Slack, Twitter, Email, LinkedIn)

Contributors

Thanks go out to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind are welcome!