From e7d9108b5026f745e902f9354b5429d995c6bd5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Urba=C5=84czyk?= Date: Wed, 10 Mar 2021 14:06:18 +0100 Subject: [PATCH] docs: add documentation for generators (#116) --- README.md | 38 +++++++++----- docs/{customisation.md => customization.md} | 2 +- docs/generators.md | 55 +++++++++++++++++++++ 3 files changed, 82 insertions(+), 13 deletions(-) rename docs/{customisation.md => customization.md} (99%) create mode 100644 docs/generators.md diff --git a/README.md b/README.md index abae6eab82..7c3aecf4b2 100644 --- a/README.md +++ b/README.md @@ -24,11 +24,13 @@ This package is under development and it has not reached version 1.0.0 yet, whic - [Installation](#installation) - [How it works](#how-it-works) - * [The transformation process](#the-transformation-process) - * [The simplification process](#the-simplification-process) - * [The generatiion process](#the-generatiion-process) + * [The input process](#the-input-process) + * [The generation process](#the-generation-process) - [Example](#example) -- [Customisation](#customisation) +- [Supported input](#supported-input) + * [AsyncAPI input](#asyncapi-input) + * [JSON Schema input](#json-schema-input) +- [Customization](#customization) - [Development](#development) - [Contributing](#contributing) @@ -41,6 +43,7 @@ Run this command to install the SDK in your project: ```bash npm install --save @asyncapi/generator-model-sdk ``` + ## How it works The process of creating data models from input data consists of 2 processes, the input and generation process. @@ -48,20 +51,21 @@ The process of creating data models from input data consists of 2 processes, the ### 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 a another input processor. + +- [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](#AsyncAPI-input) Read more about the input process [here](./docs/input_processing.md). ### The generation process -The generation process uses the predefined `CommonModel`s from the input stage to easily generate models regardless of input. The generator support the following output languages: +The generation process uses the predefined `CommonModel`s from the input stage to easily generate models regardless of input. The package supports the following output languages: - JavaScript - TypeScript - Java -Check out [the example](#example) to see how to use the library. +Check out [the example](#example) to see how to use the library and [generators document](./docs/generators.md) for more info. > **NOTE**: Each implemented language has different options, dictated by the nature of the language. Keep this in mind when selecting a language. @@ -101,28 +105,38 @@ interface Address { } ``` ## 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) + +- 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 + +- Generate from a pure JS object: + ```js generator.generate({asyncapi: '2.0.0'}); ``` + ### JSON Schema input -- Generate from a pure JS object + +- Generate from a pure JS object: + ```js generator.generate({$schema: 'http://json-schema.org/draft-07/schema#'}); ``` -## Customisation +## Customization -The AsyncAPI Model SDK uses **preset** objects to extend the rendered model. For more information, check [customisation document](./docs/customisation.md). +The AsyncAPI Model SDK uses **preset** objects to extend the rendered model. For more information, check [customization document](./docs/customization.md). ## Development diff --git a/docs/customisation.md b/docs/customization.md similarity index 99% rename from docs/customisation.md rename to docs/customization.md index 30d0f231c7..b62d10c4b3 100644 --- a/docs/customisation.md +++ b/docs/customization.md @@ -1,4 +1,4 @@ -# Customisation +# Customization The AsyncAPI Model SDK uses **preset** objects to extend the rendered model. diff --git a/docs/generators.md b/docs/generators.md new file mode 100644 index 0000000000..59980a68ce --- /dev/null +++ b/docs/generators.md @@ -0,0 +1,55 @@ +# Generators + +**Generators** are classes that are used to render models for a given language. + +## Supported languages + +- [JavaScript](../src/generators/javascript/JavaScriptGenerator.ts), +- [TypeScript](../src/generators/typescript/TypeScriptGenerator.ts), +- [Java](../src/generators/java/JavaGenerator.ts). + +## Generator's options + +Each generator extends default options for the generator. It means that the generator can also have additional options. + +Options are passed as the first argument to the generator's constructor. Check the example: + +```ts +const generator = new TypeScriptGenerator({ ...options }); +``` + +Default options contain: + +| Option | Type | Description | Default value | +|---|---|---|---| +| `indentation` | Object | Options for indentation. | - | +| `indentation.type` | String | Type of indentation. Its value can be either `SPACES` or `TABS`. | `SPACES` | +| `indentation.size` | String | Size of indentation. | 2 | +| `defaultPreset` | Object | Default preset for generator. For more information, read [customization](./customization.md) document. | _Implemented by generator_ | +| `presets` | Array | Array contains **presets**. For more information, read [customization](./customization.md) document. | `[]` | + +Below is a list of additional options available for a given generator. + +### [TypeScript](../src/generators/typescript/TypeScriptGenerator.ts) + +| Option | Type | Description | Default value | +|---|---|---|---| +| `renderTypes` | Boolean | Render signature for types. | `true` | +| `modelType` | String | It indicates which model type should be rendered for the `object` type. Its value can be either `interface` or `class`. | `class` | + +## Custom generator + +The minimum set of required actions to create a new generator are: + +- Source code must be included in [generators](../src/generators) folder. +- Must extend the abstract [`AbstractGenerator`](../src/generators/AbstractGenerator.ts) class, +- Must define [`Preset`](./customization.md)'s shape for the language, +- Must define language options by passing an interface describing additional options to the first generic argument of [`AbstractGenerator`](../src/generators/AbstractGenerator.ts). The interface must also be extended by `CommonGeneratorOptions` interface, +- Must define default options as static class's field, which must be extended by `defaultGeneratorOptions`, +- Default options must include `defaultPreset` property, +- Must implement `render` function, +- Must define **Renderers** classes for available model types in a given language. **Renderer** is an instance of the class with common helper functions to render appropriate model type and must be extended by [`AbstractRenderer`](../src/generators/AbstractRenderer.ts) class - [example](../src/generators/typescript/renderers/ClassRenderer.ts). + +Check the [generator implementation](../src/generators/typescript/TypeScriptGenerator.ts) for `TypeScript` language to see how it should look like. + +If you created a generator then you can contribute it to the AsyncAPI Model SDK and it will become the official supported generator.