Skip to content

Commit

Permalink
docs: initial setup for user-centric docs (asyncapi#338)
Browse files Browse the repository at this point in the history 
Co-authored-by: Alejandra Quetzalli  <19964402+alequetzalli@users.noreply.github.com>
  • Loading branch information
@jonaslagoni @quetzalliwrites
jonaslagoni and quetzalliwrites authored Sep 22, 2021
1 parent 70aa0ab commit e82f1ef
Show file tree
Hide file tree
Showing 56 changed files with 17,338 additions and 320 deletions.
14 changes: 14 additions & 0 deletions .eslintrc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -198,6 +198,20 @@
"@typescript-eslint/no-non-null-assertion": "off",
"@typescript-eslint/no-unused-vars": "off"
}
},
{
"files": "examples/**/*.ts",
"rules": {
"no-undef": "off",
"no-console": "off",
"security/detect-non-literal-fs-filename": "off",
"sonarjs/no-duplicate-string": "off",
"security/detect-object-injection": "off",
"max-nested-callbacks": "off",
"sonarjs/no-identical-functions": "off",
"@typescript-eslint/no-non-null-assertion": "off",
"@typescript-eslint/no-unused-vars": "off"
}
}
]
}
181 changes: 68 additions & 113 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,22 @@
<br>
<a href="https://www.asyncapi.org"><img src="https://github.com/asyncapi/parser-nodejs/raw/master/assets/logo.png" alt="AsyncAPI logo" width="200"></a>
<br>
Modelina
<em><b>Modelina</b></em>
</h5>
<p align="center">
<em>The official SDK for generating data models from JSON Schema and AsyncAPI spec</em>
<em>Modelina is the official AsyncAPI SDK used to generate different data models (i.e. <a href="#outputs">Java/TypeScript classes, Go Structs, etc</a>) for <a href="#inputs">AsyncAPI documents, among other supported inputs </a>.</em>
</p>

[![Coverage Status](https://coveralls.io/repos/github/asyncapi/modelina/badge.svg?branch=master)](https://coveralls.io/github/asyncapi/modelina?branch=master)
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
[![All Contributors](https://img.shields.io/badge/all_contributors-8-orange.svg?style=flat-square)](#contributors-)
<!-- ALL-CONTRIBUTORS-BADGE:END -->

AsyncAPI Model SDK is a set of classes/functions for generating data models from JSON Schema and AsyncAPI spec.

---

## :loudspeaker: ATTENTION:

This package is under development and it has not reached version 1.0.0 yet, which means its API might get breaking changes without prior notice. Once it reaches its first stable version, we'll follow semantic versioning.
This package is still under development and has not reached version 1.0.0 yet. This means that its API may contain breaking changes until we're able to deploy the first stable version and begin semantic versioning. Please use tests to ensure expected outputs or to hardcode the version.

---

Expand All @@ -29,14 +27,9 @@ This package is under development and it has not reached version 1.0.0 yet, whic

- [Requirements](#requirements)
- [Installation](#installation)
- [How it works](#how-it-works)
* [The input process](#the-input-process)
* [The generation process](#the-generation-process)
- [Example](#example)
- [Supported input](#supported-input)
* [AsyncAPI input](#asyncapi-input)
* [JSON Schema input](#json-schema-input)
- [Customization](#customization)
- [Features](#features)
- [Roadmap](#roadmap)
- [Documentation](#documentation)
- [Development](#development)
- [Contributing](#contributing)
- [Contributors ✨](#contributors-%E2%9C%A8)
Expand All @@ -50,117 +43,79 @@ This package is under development and it has not reached version 1.0.0 yet, whic
Feel free to submit an issue if you require this project in other use-cases.

## Installation

Run this command to install the SDK in your project:
Run this command to install Modelina in your project:

```bash
npm install --save @asyncapi/modelina
npm install @asyncapi/modelina
```

## How it works

The process of creating data models from input data consists of 2 processes, the input and generation process.

### The input process

The input process ensures that any supported input is handled correctly, the basics are that any input needs to be converted into our internal model representation `CommonModel`. The following inputs are supported:

- [JSON Schema Draft 7](#JSON-Schema-input), this is the default inferred input if we cannot find another input processor.
- [AsyncAPI version 2.0.0 and 2.1.0](#AsyncAPI-input)

Read more about the input process [here](./docs/input_processing.md).

### The generation process
Once you've successfully installed Modelina in your project, it's time to select your generator. Check out the [examples](#examples) for the specific code.

The generation process uses the predefined `CommonModel`s from the input stage to easily generate models regardless of input.
The list of supported output languages can be found [here](./docs/generators.md#supported-languages).
## Features
The following table provides a short summary of available features for supported output languages.

Check out [the example](#example) to see how to use the library and [generators document](./docs/generators.md) for more info.
To see the complete feature list for each language, please click the individual links for each language.

> **NOTE**: Each implemented language has different options, dictated by the nature of the language.
## Example

```js
import { TypeScriptGenerator } from '@asyncapi/modelina';

const generator = new TypeScriptGenerator({ modelType: 'interface' });

const doc = {
$id: "Address",
type: "object",
properties: {
street_name: { type: "string" },
city: { type: "string", description: "City description" },
house_number: { type: "number" },
marriage: { type: "boolean", description: "Status if marriage live in given house" },
pet_names: { type: "array", items: { type: "string" } },
state: { type: "string", enum: ["Texas", "Alabama", "California", "other"] },
},
required: ["street_name", "city", "state", "house_number", "state"],
};

async function generate() {
const models = await generator.generate(doc);
models.forEach(model => console.log(model.result));
}

generate();
```

Output:

```ts
export interface Address {
streetName: string;
city: string;
houseNumber: number;
marriage?: boolean;
petNames?: Array<string>;
state: State;
additionalProperties?: Map<String, object | string | number | Array<unknown> | boolean | null | number>;
}
export enum State {
TEXAS = "Texas",
ALABAMA = "Alabama",
CALIFORNIA = "California",
OTHER = "other",
}
```

## Supported input

These are the supported inputs.

### AsyncAPI input

The library expects the `asyncapi` property for the document to be sat in order to understand the input format.

- Generate from a [parsed AsyncAPI document](https://github.com/asyncapi/parser-js):

```js
const parser = require('@asyncapi/parser');
const doc = await parser.parse(`{asyncapi: '2.0.0'}`);
generator.generate(doc);
```

- Generate from a pure JS object:

```js
generator.generate({asyncapi: '2.0.0'});
```

### JSON Schema input
<a id="inputs"></a>
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
<tr>
<th>Supported inputs</th>
<th>description</th>
</tr>
<tr>
<td><a href="./docs/usage.md#generate-typescript-models">AsyncAPI</a></td>
<td>We support the following AsyncAPI versions: <em>2.0.0, 2.1.0</em>, which generates models for all the defined message payloads.</td>
</tr>
<tr>
<td><a href="./docs/usage.md#generate-java-models">JSON Schema</a></td>
<td>We support the following JSON Schema versions: <em>Draft-4, Draft-6, Draft-7</em></td>
</tr>
<tr>
<td><a href="./docs/usage.md#generate-c#-models">OpenAPI</a></td>
<td>We support the following OpenAPI versions: <em>Swagger 2.0, OpenAPI 3.0.x, OpenAPI 3.1</em>, which generates models for all defined responses.</td>
</tr>
</table>

- Generate from a pure JS object:
<a id="outputs"></a>
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
<tr>
<th>Supported outputs</th>
<th>Features</th>
</tr>
<tr>
<td><a href="./docs/usage.md#generate-java-models">Java</a></td>
<td>Class and enum generation: <em>generation of equals, hashCode, toString, Jackson annotation, custom indentation type and size, etc</em></td>
</tr>
<tr>
<td><a href="./docs/usage.md#generate-typescript-models">TypeScript</a></td>
<td>Class, interface and enum generation: <em>generation of example code, un/marshal functions, custom indentation type and size, etc</em></td>
</tr>
<tr>
<td><a href="./docs/usage.md#generate-c#-models">C#</a></td>
<td>Class and enum generation: <em>generation of example code, serializer and deserializer functions, custom indentation type and size, etc</em></td>
</tr>
<tr>
<td><a href="./docs/usage.md#generate-go-models">Go</a></td>
<td>Struct and enum generation: <em>custom indentation type and size, etc </em></td>
</tr>
<tr>
<td><a href="./docs/usage.md#generate-javascript-models">JavaScript</a></td>
<td>Class generation: <em>custom indentation type and size, etc</em></td>
</tr>
</table>

```js
generator.generate({$schema: 'http://json-schema.org/draft-07/schema#'});
```
## Roadmap
- [Reach version 1.0](https://github.com/asyncapi/modelina/milestone/3)

## Customization
## Documentation
The documentation for this library can all be found under the documentation [README](./docs/README.md).

There are multiple ways to customize the library both in terms of processing, logging and output generation, check the [customization document](./docs/customization.md).
## Examples
We have gathered all the examples, in a separate folder to ensure consistency, they can be found under the [example folder](./examples).

## Development
To setup your development environment please read the [development](./docs/development.md) document.
Expand Down
51 changes: 51 additions & 0 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Documentation

<!-- toc is generated with GitHub Actions do not remove toc markers -->

<!-- toc -->

- [Usage](#usage)
- [Advanced](#advanced)
- [Integration](#integration)
- [Development](#development)
- [Input processing](#input-processing)
- [Generators](#generators)
- [Presets](#presets)
- [Interpretation of JSON Schema draft 7](#interpretation-of-json-schema-draft-7)
- [Languages](#languages)

<!-- tocstop -->

This document gives the overview of all the available documentation for Modelina.

### [Usage](./usage.md)
Contains simple use-cases that you'll encounter when using Modelina.

### [Advanced](./advanced.md)
Contains many of the advanced use-cases that you may stumble upon when pushing the limits of Modelina.

### [Integration](./integration.md)
Contains many advanced ways to integrate Modelina _(i.e. websites)_.

### [Development](./development.md)
Explains how to setup the project for development.

### [Input processing](./input_processing.md)
Details how input processing works.

### [Generators](./generators.md)
Details which different generator options are supported.

### [Presets](./presets.md)
Goes more in-depth into how the preset system works, which enables full customization of generators.

### [Interpretation of JSON Schema draft 7](./interpretation_of_JSON_Schema_draft_7.md)
Explains how a JSON Schema draft 7 schema is interpreted to a data model.

### Languages
Each language has its own limitations, corner cases, and features; thus, each language has separate documentation.
- [C#](./languages/Csharp.md)
- [Go](./languages/Go.md)
- [Java](./languages/Java.md)
- [JavaScript](./languages/JavaScript.md)
- [TypeScript](./languages/TypeScript.md)
65 changes: 65 additions & 0 deletions docs/advanced.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Advanced use-cases for Modelina
This document contains many of the advanced use-cases that you may stumble upon when pushing the limits of Modelina.

<!-- toc is generated with GitHub Actions do not remove toc markers -->

<!-- toc -->

- [Generate each model in the same file](#generate-each-model-in-the-same-file)
- [Generate a model in separate files](#generate-a-model-in-separate-files)
- [Include a custom function in the data model](#include-a-custom-function-in-the-data-model)
- [Use the models for data transfer](#use-the-models-for-data-transfer)
- [Extend the logic of an existing renderer](#extend-the-logic-of-an-existing-renderer)
- [Build your own model renderer](#build-your-own-model-renderer)
- [Create your own models from the ground up, instead of a supported input](#create-your-own-models-from-the-ground-up-instead-of-a-supported-input)
- [Add logging to library](#add-logging-to-library)
* [Example usage](#example-usage)
- [Change the generated indentation type and size](#change-the-generated-indentation-type-and-size)
- [Change the naming format for properties](#change-the-naming-format-for-properties)
- [Change the naming format for data models](#change-the-naming-format-for-data-models)

<!-- tocstop -->

## Generate each model in the same file
TODO

## Generate a model in separate files
TODO

## Include a custom function in the data model
TODO

## Use the models for data transfer
TODO

## Extend the logic of an existing renderer
TODO

## Build your own model renderer
TODO

## Create your own models from the ground up, instead of a supported input
TODO


## Add logging to library
When you generate models, by default, nothing is logged to the console or elsewhere.

If you want to integrate a logging implementation specific to your needs, this library allows you to implement a detached logging module.

The library uses 4 different logging levels:
- `debug`: for specific details only relevant to debugging
- `info`: for general information relevant to the user
- `warn`: for warnings a user may need if the output is not as expected
- `error`: for errors that occur in the library

Check out this [example out for a live demonstration](../examples/custom-logging).

## Change the generated indentation type and size
TODO

## Change the naming format for properties
TODO

## Change the naming format for data models
TODO
9 changes: 0 additions & 9 deletions docs/customization.md
View file

This file was deleted.

6 changes: 3 additions & 3 deletions docs/development.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Development guideline
# Development
These are some of the development guidelines and help to setup the library for development.

## Docker
Expand All @@ -14,8 +14,8 @@ You can either build the image and run the needed commands manually or rather us
To setup the environment follow these steps:
1. Setup the project by first installing the dependencies `npm install`
2. Make sure the tests pass by running `npm run test` script
- [blackbox testing](#blackbox-testing) are excluded when running the `test` script because it require some extra setup. Please refer to [Blackbox testing section](#blackbox-testing) below.
- You can update snapshots by running `npm run test:snapshots`
- [Blackbox testing](#blackbox-testing) are excluded when running the `test` script because it require some extra setup. Please refer to [Blackbox testing section](#blackbox-testing) below.
- You can update snapshots by running `npm run test -- -u`
3. Make sure code is well formatted and secure `npm run lint`

## Blackbox testing
Expand Down
Loading

0 comments on commit e82f1ef

Please sign in to comment.