Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/asyncapi/modelina
A library for generating typed models based on inputs such as AsyncAPI, OpenAPI, and JSON Schema documents with high customization
https://github.com/asyncapi/modelina
asyncapi codegen codegenerator cpp csharp generate-code get-global-node-release-workflows go java json-schema kotlin modelina openapi2 openapi3 php rust swagger typescript
Last synced: 10 days ago
JSON representation
A library for generating typed models based on inputs such as AsyncAPI, OpenAPI, and JSON Schema documents with high customization
- Host: GitHub
- URL: https://github.com/asyncapi/modelina
- Owner: asyncapi
- License: apache-2.0
- Created: 2021-01-21T12:27:51.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2024-10-29T14:27:22.000Z (12 days ago)
- Last Synced: 2024-10-29T17:18:27.581Z (12 days ago)
- Topics: asyncapi, codegen, codegenerator, cpp, csharp, generate-code, get-global-node-release-workflows, go, java, json-schema, kotlin, modelina, openapi2, openapi3, php, rust, swagger, typescript
- Language: TypeScript
- Homepage: https://modelina.org
- Size: 20.2 MB
- Stars: 312
- Watchers: 7
- Forks: 180
- Open Issues: 46
-
Metadata Files:
- Readme: README.md
- Contributing: docs/contributing.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
[](https://www.modelina.org)
[![blackbox pipeline status]()](https://github.com/asyncapi/modelina/actions/workflows/blackbox-testing.yml?query=branch%3Amaster++)
[](https://coveralls.io/github/asyncapi/modelina?branch=master)
[](https://www.repostatus.org/#active)
[](https://www.npmjs.com/package/@asyncapi/modelina)
[](https://github.com/asyncapi/modelina/blob/master/LICENSE)
[](https://github.com/asyncapi/modelina/commits/master)
[](https://github.com/asyncapi/modelina/discussions)
[](https://www.modelina.org)
[](https://www.modelina.org/playground)
[](#contributors-)
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](#installing-modelina)
- [AsyncAPI CLI](#asyncapi-cli)
- [Features](#features)
- [Requirements](#requirements)
- [Documentation](#documentation)
- [Examples](#examples)
- [Versioning and maintenance](#versioning-and-maintenance)
- [Development](#development)
- [Contributing](#contributing)
- [Contributors](#contributors)
## Installing Modelina
Run this command to install Modelina in your project:
```bash
npm install @asyncapi/modelina
```
## AsyncAPI CLI
If you have the [AsyncAPI CLI installed](https://github.com/asyncapi/cli#installation) (ONLY support AsyncAPI inputs), you can run the following command to use [Modelina](https://github.com/asyncapi/cli#usage):
```bash
asyncapi generate models ./asyncapi.json
```
What Does Modelina Do?
Modelina put YOU in control of your data models, here is how...
Modelina lets you generate data models from many types of inputs
```typescript
const asyncapi = ...
const jsonschema = ...
const openapi = ...
const metamodel = ...
...
const models = await generator.generate(
asyncapi | jsonschema | openapi | metamodel
);
```
Use the same inputs across a range of different generators
```typescript
const generator = new TypeScriptGenerator();
const generator = new CsharpGenerator();
const generator = new JavaGenerator();
const generator = new RustGenerator();
...
const models = await generator.generate(input);
```
Easily let you interact with the generated models.
- 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.
```typescript
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;
...
}
```
Easily modify how models are constrained into the output
```typescript
const generator = new TypeScriptGenerator({
constraints: {
modelName: ({modelName}) => {
// Implement your own constraining logic
return modelName;
}
}
});
```
Seamlessly layer additional or replacement code on top of each other to customize the models to your use-case
```typescript
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);
```
Seamlessly lets you combine multiple layers of additional or replacement code
```typescript
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.
Supported inputs
AsyncAPI
We support the following AsyncAPI versions: 2.0.0 -> 2.6.0, which generates models for all the defined message payloads. It supports the following schemaFormats AsyncAPI Schema object, JSON Schema draft 7, AVRO 1.9, RAML 1.0 data type, and OpenAPI 3.0 Schema.
JSON Schema
We support the following JSON Schema versions: Draft-4, Draft-6 and Draft-7
OpenAPI
We support the following OpenAPI versions: Swagger 2.0, OpenAPI 3.0 and 3.1, which generates models for all the defined request and response payloads.
TypeScript
We currently support TypeScript types as file input for model generation
Meta model
This is the internal representation of a model for Modelina, it is what inputs gets converted to, and what generators are provided to generate code. Instead of relying on an input processor, you can create your own models from scratch and still take advantage on the generators and the features.
Supported outputs
Java
Class and enum generation: generation of equals, hashCode, toString, Jackson annotation, custom indentation type and size, etc
TypeScript
Class, interface and enum generation: generation of example code, un/marshal functions, custom indentation type and size, etc
C#
Class and enum generation: generation of example code, serializer and deserializer functions, custom indentation type and size, etc
Go
Struct and enum generation: custom indentation type and size, etc
JavaScript
Class generation: custom indentation type and size, etc
Dart
Class and enum generation: json_annotation
Rust
Struct/tuple and enum generation: generation of `implement Default`, generate serde macros, custom indentation type and size, etc
Python
Class and enum generation: custom indentation type and size, etc
Kotlin
Class and enum generation: use of data classes where appropriate, custom indentation type and size, etc
C++
Class and enum generation: custom indentation type and size, etc
PHP
Class and enum generation: custom indentation type and size, descriptions, etc
Scala
Class and enum generation: custom indentation type and size, descriptions, etc
## Requirements
The following are a requirement in order to use Modelina.
- [NodeJS](https://nodejs.org/en/) >= 18
## Documentation
A feature in Modelina cannot exists without an example and documentation for it. You can find all the [documentation here](./docs/README.md).
## 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](./examples).
## 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](./docs/development.md).
## 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](./docs/champions.md).
We have made quite a [comprehensive contribution guide](./docs/contributing.md) 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](https://asyncapi.com/slack-invite) under the `#04_tooling` channel
- Tag a specific [CODEOWNER](./CODEOWNERS) 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](https://github.com/jonaslagoni) (on [AsyncAPI Slack](https://asyncapi.com/slack-invite), [Twitter](https://twitter.com/jonaslagoni), [Email](mailto:[email protected]), [LinkedIn](https://www.linkedin.com/in/jonaslagoni/))
## Contributors
Thanks go out to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Maciej UrbaΕczyk
π π» π π€ π§ π¬ β οΈ π
czlowiek488
π π π€
Sergio Moya
π π» β οΈ π π
Jonas Lagoni
π π» π π€ π§ π¬ β οΈ π
Lukasz Gornicki
π π π»
Arjun Garg
π»
Fran MΓ©ndez
π
Kanwal Singh
π»
Alejandra Quetzalli
π π
MD SAIF HUSAIN
π‘ β οΈ π π»
Sudipto Ghosh
π‘ β οΈ π
panwauu
π» β οΈ π‘ π π
Stefan E. Mayer
π
Talmiz Ahmed
π β οΈ π‘
Marco
π
quadrrem
π» β οΈ
Kamil JaneΔek
β οΈ π π»
mahakporwal02
π‘ β οΈ π π»
Debajyoti Halder
π» β οΈ π π‘ π§
Ritik Rawal
π π» β οΈ π‘
Ishan
π» β οΈ
Samriddhi
π» β οΈ π π‘ π§
GΓ‘bor Magyar
π» β οΈ π π‘
ibernabeudev
π» β οΈ π‘ π
Arkadiusz SΕowikowski
π» β οΈ π‘ π
Willem Gillis
π» β οΈ π
rmasarovic
π» π β οΈ π‘
Owais Hasnath Ahmed
π» β οΈ π
PanMan
π
artur-ciocanu
π» π π‘ π β οΈ π§
Cyprian Gracz
π» β οΈ π
Leigh Johnson
π» β οΈ π‘ π π§ π
Nitin Tejuja
β οΈ π‘
Kenneth Aasan
π» β οΈ π§ π
Amit Kumar Sharma
β οΈ π π‘
Andrey Zaytsev
π» π‘ π β οΈ
Tenshi Codes
π
Yushi OMOTE
π π»
Zbigniew Malcherczyk
π π π» π‘ β οΈ π
200Puls
π» β οΈ
Anay Sarkar
π‘ π» β οΈ
Louis Xhaferi
π»
Sambhav Gupta
π π π¨ π» π
Abhay Garg
π» π‘ β οΈ π
henrikjon
π» β οΈ π π‘
Mohammad Yasir
π»
Savio Dias
π» π π
Ishaan Shah
π»
Shreyas0410
π»
beku-epitome
π» π β οΈ
Joshua Michael Daly
π
Daniel KJ
π» β οΈ π‘ π
Bhavik Agarwal
π¨
Rishi
π» π¨
Rohith Boppey
π» π¨
Ashish Padhy
π» β οΈ π
Jean-François Côté
π» β οΈ π‘ π
Sumant.xD
β οΈ π π»
Aryan Singh
π»
Markus Poerschke
π» β οΈ π‘ π
James Moey
π» β οΈ
tomwolanski
π
Kristupas
π»
Devansh-Bhatt
β οΈ π
Ansh Pancholi
π»
Maeght Loan
π» π
Prince Rajpoot
π»
harshit mishra
π»
PeteAudinate
π»
jano-petras
π» π β οΈ
Nilkanth Parmar
π» β οΈ π‘ π
Ashmit JaiSarita Gupta
π» π¨ π π§ β οΈ π
Harshil Jani
π» β οΈ
Mintu Gogoi
β οΈ
Devansh Mahant
π
Asish Kumar
π
Ankur Singh
π
RowlandBanks
π» β οΈ π
Moritz Kalwa
π» β οΈ π π
Akshit Gupta
π» π π‘ β οΈ π
Athul Tulasidasan
π» π‘ π β οΈ
souvik
π» β οΈ π‘ π
Louis-PhilippeGentile
π» β οΈ π π
Akhil Jamwal
π» β οΈ
Anders Hellerup Madsen
π» β οΈ π
rquinio1A
π» π‘
gitankit7
π»
Janne Husberg
π» β οΈ π
borrull
π» β οΈ
Kamil Zuzda
π»
jespitae
π» β οΈ π
Axel Hecht
π» β οΈ
Tom de Vroomen
π» π‘ π β οΈ
memdal
π» β οΈ
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome!