|
| 1 | +# Writing your own templates |
| 2 | + |
| 3 | +- Any templates that in the templates folder at compilation time will be embedded in the compiled binary. |
| 4 | +- If you only have the binary you can put templates in the folder `user-templates`. |
| 5 | + If a file from the `user-templates` folder has the same path as an embedded template, only the template from `user-template` will be rendered. |
| 6 | + - set the command line argument `--user-templates` or `-u` to set a custom folder |
| 7 | +- the last file extension will be removed e.g: `file.rs.go` will be rendered to `file.rs`. |
| 8 | +- For examples refer to the allready included [templates](https://github.com/Programmierpraktikum-MVA/AsyncAPI/tree/d05d047c5ea9dfb221f31ecbf5af03387103e342/templates) |
| 9 | + |
| 10 | + |
| 11 | + |
| 12 | +## What fields are available inside templates? |
| 13 | + |
| 14 | +Any of these fields will be accessible: |
| 15 | +```rust,noplayground |
| 16 | + pub struct TemplateContext<'a> { |
| 17 | + pub title: &'a String, |
| 18 | + pub description: &'a Option<String>, |
| 19 | + pub server: &'a Server, |
| 20 | + pub subscribe_channels: Vec<(&'a String, SimplifiedOperation)>, |
| 21 | + pub publish_channels: Vec<(&'a String, SimplifiedOperation)>, |
| 22 | + pub model: Model, |
| 23 | + } |
| 24 | + |
| 25 | + pub struct Model { |
| 26 | + pub message_models: Vec<RustSchemaRepresentation>, |
| 27 | + // pub enums: Vec<MultiStructEnum>, |
| 28 | + } |
| 29 | + |
| 30 | + pub struct SimplifiedOperation { |
| 31 | + pub unique_id: String, |
| 32 | + pub original_operation: Operation, |
| 33 | + // array, da es eine oder mehrere messages geben kann |
| 34 | + pub messages: Vec<SimplifiedMessage>, |
| 35 | + // pub multiple_messages_enum: Option<MultiStructEnum>, |
| 36 | + } |
| 37 | + |
| 38 | + pub struct MultiStructEnum { |
| 39 | + pub unique_id: String, |
| 40 | + pub messages: Vec<SimplifiedMessage>, |
| 41 | + pub struct_definition: String, |
| 42 | + } |
| 43 | + |
| 44 | + pub struct SimplifiedMessage { |
| 45 | + pub unique_id: String, |
| 46 | + pub original_message: Message, |
| 47 | + pub payload: Option<RustSchemaRepresentation>, |
| 48 | + } |
| 49 | +``` |
| 50 | +- for more information about the fields available from these structs please refer to: [all rust structs](https://github.com/Programmierpraktikum-MVA/AsyncAPI/tree/main/src/asyncapi_model) |
| 51 | + |
| 52 | + |
| 53 | + |
| 54 | +## Render to separate files |
| 55 | + |
| 56 | +It is possible to generate files for each specific object in your AsyncAPI documentation. For example, you can specify a filename like `$$handler$$.rs.go` to generate a file for each `publish_channel` defined in your AsyncAPI spec. |
| 57 | + |
| 58 | +This works with file templates that include the following in their name: |
| 59 | +- `$$handler$$` |
| 60 | +- `$$producer$$` |
| 61 | +- `$$model$$` |
| 62 | +- `$$schemas$$` |
| 63 | + |
| 64 | + |
| 65 | + |
| 66 | +## Functions available inside the templates |
| 67 | + |
| 68 | +- `to_lower(input: String) -> String` converts String to lowercase |
| 69 | +- `key_exists(input: String) -> String` checks if key exists |
| 70 | +- `camel_to_snake_case(input :String) -> String` converts a String in camelCase to snake_case |
| 71 | +- `replace(input: String, from: String, to: String) -> String` replaces `from` with `to` for `input` |
| 72 | + - Side Note: these functions are defined in `src/generator/template_functions.rs` feel free to extend then, if you have access to the source code. |
| 73 | + |
0 commit comments