Tools Overview, OpenAPI, Protocol Buffers, GraphQL, Jolie, Java, AsyncAPI

Arbitrary Text Generation with Freemarker Templates

The MDSL Eclipse plugin and the CLI allow API designers to generate arbitrary text files out of MDSL by using a Freemarker template.

Usage

You can generate any text out of an MDSL model by using the Eclipse plugin or our CLI.

In Eclipse you find the generator in the MDSL context menu:

The following command generates the Java code in case you work with the CLI:

./mdsl -i model.mdsl -g text template.md.ftl -f my-report.md

Hint: Both tools generate the output into the src-gen folder which is located in the projects root directory (Eclipse) or the directory from which the mdsl command has been called (CLI). Both tools create the directory automatically in case it does not already exist.

Example

The following example illustrates what the generator can produce for an exemplary freemarker template and MDSL contract.

You find the complete sources (incl. generated text file) of this example here.

The following MDSL model, taken from this blogpost, illustrates the generator usage:

API description ReferenceManagementServiceAPI

data type PaperItemDTO { "title":D<string>, "authors":D<string>, "venue":D<string>, "paperItemId":PaperItemKey }
data type PaperItemKey { "doi":D<string> }
data type createPaperItemParameter { "who":D<string>, "what":D<string>, "where":D<string> }

endpoint type PaperArchiveFacade
  serves as INFORMATION_HOLDER_RESOURCE
  exposes
    operation createPaperItem
      with responsibility STATE_CREATION_OPERATION
      expecting
        payload createPaperItemParameter
      delivering
        payload PaperItemDTO
    operation lookupPapersFromAuthor
      with responsibility RETRIEVAL_OPERATION
      expecting
        payload D<string>
      delivering
        payload PaperItemDTO*
    operation convertToMarkdownForWebsite
      expecting
        payload PaperItemKey
      delivering
        payload D<string>

Let us use the following very basic Freemarker template to generate some exemplary output from the above MDSL:

# Report for MDSL specification ${fileName}

## Endpoint Types 

The API description ${genModel.apiName} features the following endpoint types (a.k.a. service contracts): 

<#list genModel.endpoints as endpoint>
* ${endpoint.name} 
</#list>

The template simply generates a markdown report listing the available endpoints.

Applied to the ReferenceManagementServiceAPI description above, the generator produces the following markdown file:

# Report for MDSL specification ReferenceManagementAPI.mdsl

## Endpoint Types 

The API description ReferenceManagementServiceAPI features the following endpoint types (a.k.a. service contracts): 

* PaperArchiveFacade

You find the complete sources (incl. generated text file) of this and other examples here.

The entire MDSL grammar is available as a data model to the Freemarker templating feature.

Generator Model for Freemarker Templating and Model Exports

To ease code generation with the template-based generator (Freemarker Templating, explained above), we provide an intermediate model. The following class diagram illustrates it:

The MDSLGeneratorModel object is the root object of the model and available in Freemarker templates in the variable genModel (used in the example above).

This model can also be exported for offline processing (for instance, to feed other tools):

• Export Generator Model as JSON
• Export Generator Model as YAML

Note: This feature is not yet complete, and the model API subject to change at any time. We do use it internally in the GraphQL schema and Java generators, so it has reached a certain level of maturity and test coverage. That said, it also has some known limitations; for instance, the output can be rather verbose and partially redundant (input depending, of course).

Other Generators

Also checkout our other generators:

• OpenAPI generator
• Protocol Buffers generator
• GraphQL generator
• Jolie generator
• Java generator

Site Navigation

• Back to tools page.
• Quick reference and tutorial.
• Language specification:
  • Service endpoint contract types and data contracts (schemas).
  • Bindings and instance-level concepts.
• Back to MDSL homepage.

Copyright: Stefan Kapferer and Olaf Zimmermann, 2020-2022. All rights reserved. See license information.