Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: corrected the relative paths #1302

Closed
wants to merge 6 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
356 changes: 199 additions & 157 deletions apps/generator/docs/api.md

Large diffs are not rendered by default.

8 changes: 4 additions & 4 deletions apps/generator/docs/asyncapi-document.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@ In the following sections, you'll learn about the inner working of the generator
## AsyncAPI document generation process

1. The **Generator** receives the **AsyncAPI Document** as input.
2. The **Generator** sends to the **[Parser](parser)** the **asyncapiString** is a stringified version of the original **AsyncAPI Document** to validate and parse it.
2. The **Generator** sends to the **[Parser](parser.md)** the **asyncapiString** is a stringified version of the original **AsyncAPI Document** to validate and parse it.
3. The **Parser** validates the **AsyncAPI Document** using additional schema-related plugins, either the OpenAPI schema, RAML data types, or Avro schema.
4. If the **Parser** determines that the **AsyncAPI Document** is valid, it manipulates the original JSON/YAML document and provides a set of helper functions in return, bundling them together into an **asyncapi** variable that is an instance of [**AsyncAPIDocument**](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#asyncapidocument).
5. At this point, the **Generator** passes the **originalAsyncAPI** and the **asyncapi** which make up part of the **[Template Context](template-context)** to the **Render Engine**.
6. The **Template Context** is accessible to the template files that are passed to either the [react](react-render-engine) or [nunjucks](nunjucks-render-engine) **Render Engines**.
5. At this point, the **Generator** passes the **originalAsyncAPI** and the **asyncapi** which make up part of the **[Template Context](template-context.md)** to the **Render Engine**.
6. The **Template Context** is accessible to the template files that are passed to either the [react](react-render-engine.md) or [nunjucks](nunjucks-render-engine.md) **Render Engines**.

```mermaid
graph LR
Expand Down Expand Up @@ -77,7 +77,7 @@ function createAsyncapiFile(generator) {

A major advantage of using `asyncapi` (which is an instance of `AsyncAPIDocument`) is that it enables the developer to easily access the AsyncAPI documents' content by simply invoking a function.

Once the specification YAML or JSON document is passed as input to the generator, it is passed on to the [Parser](parser) library, which then manipulates the asyncAPI document to a more structured document called the `AsyncAPIDocument`. Once the parser returns the document to the generator, the generator passes it to the render engine. The render engine makes the `AsyncAPIDocument` object accessible to your template through the `asyncapi` variable.
Once the specification YAML or JSON document is passed as input to the generator, it is passed on to the [Parser](parser.md) library, which then manipulates the asyncAPI document to a more structured document called the `AsyncAPIDocument`. Once the parser returns the document to the generator, the generator passes it to the render engine. The render engine makes the `AsyncAPIDocument` object accessible to your template through the `asyncapi` variable.

For example, if you want to extract the version of your API from AsyncAPI document, you can do that by calling `asyncapi.version()`. You can say that this one is easy to access from JSON objects, but there are more complex scenarios. For example, to get access to all messages from all channels, you can call `asyncapi.allMessages()` instead of iterating through a complex JSON object on your own.

Expand Down
40 changes: 19 additions & 21 deletions apps/generator/docs/configuration-file.md

Large diffs are not rendered by default.

41 changes: 21 additions & 20 deletions apps/generator/docs/file-templates.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,20 @@ weight: 140

It is possible to generate files for each specific object in your AsyncAPI documentation using the Nunjucks render engine. For example, you can specify a filename like `$$channel$$.js` to generate a file for each channel defined in your AsyncAPI. The following file-template names and extra variables are available:

- `$$channel$$`, within the template-file you have access to two variables [`channel`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channel) and [`channelName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channels). Where the `channel` contains the current channel being rendered.
- `$$message$$`, within the template-file you have access to two variables [`message`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#message) and [`messageName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#message). Where `message` contains the current message being rendered.
- `$$schema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema) and [`schemaName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema). Where `schema` contains the current schema being rendered. Only schemas from [Components object](https://www.asyncapi.com/docs/reference/specification/latest#componentsObject) are used.
- `$$everySchema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema) and [`schemaName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schemas). Where `schema` contains the current schema being rendered. Every [Schema object](https://www.asyncapi.com/docs/specifications/2.0.0/#schemaObject) from the entire AsyncAPI file is used.
- `$$objectSchema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema) and [`schemaName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schemas). Where `schema` contains the current schema being rendered. All the [Schema objects](https://www.asyncapi.com/docs/reference/specification/latest#multiFormatSchemaObject) with type object is used.
- `$$parameter$$`, within the template-file you have access to two variables [`parameter`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channelparameter) and [`parameterName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channelparameters). Where the `parameter` contains the current parameter being rendered.
- `$$securityScheme$$`, within the template-file you have access to two variables [`securityScheme`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#securityscheme) and [`securitySchemeName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#securityschemes). Where `securityScheme` contains the current security scheme being rendered.
- `$$channel$$`, within the template-file you have access to two variables [`channel`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channel) and [`channelName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channels). Where the `channel` contains the current channel being rendered.
- `$$message$$`, within the template-file you have access to two variables [`message`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#message) and [`messageName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#message). Where `message` contains the current message being rendered.
- `$$schema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema) and [`schemaName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema). Where `schema` contains the current schema being rendered. Only schemas from [Components object](https://www.asyncapi.com/docs/reference/specification/latest#componentsObject) are used.
- `$$everySchema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema) and [`schemaName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schemas). Where `schema` contains the current schema being rendered. Every [Schema object](https://www.asyncapi.com/docs/specifications/2.0.0/#schemaObject) from the entire AsyncAPI file is used.
- `$$objectSchema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema) and [`schemaName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schemas). Where `schema` contains the current schema being rendered. All the [Schema objects](https://www.asyncapi.com/docs/reference/specification/latest#multiFormatSchemaObject) with type object is used.
- `$$parameter$$`, within the template-file you have access to two variables [`parameter`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channelparameter) and [`parameterName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channelparameters). Where the `parameter` contains the current parameter being rendered.
- `$$securityScheme$$`, within the template-file you have access to two variables [`securityScheme`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#securityscheme) and [`securitySchemeName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#securityschemes). Where `securityScheme` contains the current security scheme being rendered.

The file name will be equal to `*Name` variable.

### Example

The file name is `$$schema$$.txt`, the content of this file is:

```
Schema name is '{{schemaName}}' and properties are:
{% for propName, prop in schema.properties() %}
Expand All @@ -30,9 +31,10 @@ Schema name is '{{schemaName}}' and properties are:
```

With the following AsyncAPI:

```
components:
schemas:
schemas:
peoplePayload:
type: object
properties:
Expand All @@ -46,12 +48,14 @@ components:
```

The generator creates two files `peoplePayload.txt` and `people.txt` with the following content:

```
Schema name is 'peoplePayload' and properties are:
- people
```

and

```
Schema name is 'people' and properties are:
- id
Expand All @@ -68,13 +72,13 @@ The above method of rendering **file templates** only works for the Nunjucks ren
The following is a simple hardcoded example of how to render multiple files using the React render engine:

```tsx
import { File} from "@asyncapi/generator-react-sdk";
import { File } from "@asyncapi/generator-react-sdk";

export default function({ asyncapi }) {
export default function ({ asyncapi }) {
return [
<File name={`file1.html`}>Content</File>,
<File name={`file2.html`}>Content</File>
]
<File name={`file2.html`}>Content</File>,
];
}
```

Expand All @@ -83,22 +87,21 @@ export default function({ asyncapi }) {
In practice, to render the multiple files, that are generated from the data defined in your AsyncAPI, you'll iterate over the array of schemas and generate a file for each schema as shown in the example below:

```js
import { File} from "@asyncapi/generator-react-sdk";
import { File } from "@asyncapi/generator-react-sdk";

/*
* To render multiple files, it is enough to return an array of `File` components in the rendering component, like in following example.
*/
export default function({ asyncapi }) {
export default function ({ asyncapi }) {
const schemas = asyncapi.allSchemas();
const files = [];
// schemas is an instance of the Map
schemas.forEach((schema) => {

files.push(
// We return a react file component and each time we do it, the name of the generated file will be a schema name
// Content of the file will be a variable representing schema
<File name={`${schema.id()}.js`}>
const { schema.id() } = { JSON.stringify(schema._json, null, 2) }
const {schema.id()} = {JSON.stringify(schema._json, null, 2)}
</File>
);
});
Expand All @@ -113,7 +116,6 @@ Additionally, you can generate multiple files for each channel defined in your A
```js
import { File, Text } from "@asyncapi/generator-react-sdk";


export default function ({ asyncapi }) {
const files = [];

Expand All @@ -124,15 +126,14 @@ export default function ({ asyncapi }) {
files.push(
<File name={`${channelName}.md`}>
<Text newLines={2}># Channel: {channelName}</Text>
<Text>
{channel.hasDescription() && `${channel.description()}`}
</Text>
<Text>{channel.hasDescription() && `${channel.description()}`}</Text>
</File>
);
});
return files;
}
```

The code snippet above uses the `Text` component to write file content to the `.md` markdown file. The `newline` property is used to ensure that the content isn't all rendered in one line in the markdown file. In summary, the code snippet above is a practical guide on generating properly formatted multiline Markdown files for each channel in an AsyncAPI document.

> You can see an example of a file template that uses the React render engine [here](https://github.com/asyncapi/template-for-generator-templates/blob/master/template/schemas/schema.js).
Loading
Loading