Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/commercetools/rmf-codegen
Provides RAML code generators based on RMF.
https://github.com/commercetools/rmf-codegen
audit-sdk code generation kotlin raml rmf
Last synced: about 2 months ago
JSON representation
Provides RAML code generators based on RMF.
- Host: GitHub
- URL: https://github.com/commercetools/rmf-codegen
- Owner: commercetools
- License: apache-2.0
- Created: 2018-06-08T15:17:50.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-10-07T20:56:10.000Z (3 months ago)
- Last Synced: 2024-11-08T06:09:32.094Z (about 2 months ago)
- Topics: audit-sdk, code, generation, kotlin, raml, rmf
- Language: Kotlin
- Homepage:
- Size: 27.2 MB
- Stars: 13
- Watchers: 27
- Forks: 7
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# RMF-Codegen
RAML API client code generators based on the [RMF (REST Modeling Framework)](https://github.com/vrapio/rest-modeling-framework).
The code generators are written in [kotlin](https://kotlinlang.org/).
## Supported output targets
- `JAVA_CLIENT`:
- Java types for JSON serialization/deserialization of RAML types via [Jackson](https://github.com/FasterXML/jackson)
- Java client for accessing RAML resources via [Spring RestTemplate](https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#webmvc-resttemplate)
- `TYPESCRIPT_CLIENT`:
- TypeScript types generated from RAML types
- TypeScript types for validating JSON payloads via [hapijs/joi](https://github.com/hapijs/joi)
- `CSHARP_CLIENT`
- `PHP_CLIENT`
- `POSTMAN`: Collection file for the [Postman API Client](https://www.postman.com/product/api-client/)
- `RAML_DOC`: Emits RAML files targeted at generating robust and stable API documentation. Fully flattens and resolves types and resources. The output RAML has a fixed canonical filesystem structure and every type or resource file contains all information to fully document it. It's used by the [commercetools-docs-kit](https://github.com/commercetools/commercetools-docs-kit/tree/master/packages/gatsby-theme-api-docs)
## Install `rmf-codegen` CLI
To install the rmf-codegen cli, run the following command
```
curl -o- -s https://raw.githubusercontent.com/commercetools/rmf-codegen/main/scripts/install.sh | bash
```
You will find a new command available `rmf-codegen`, you can check that all is good by executing `rmf-codegen -v`
## NPM wrapper package
The [`commercetools-docs-kit`](https://github.com/commercetools/commercetools-docs-kit) provides an NPM package that automates the download of the JAR and provides the `rmf-codegen` command to JavaScript projects without global installation. (find at [NPM](https://www.npmjs.com/login?next=/package/@commercetools-docs/rmf-codegen))
## Docker
Docker images for the code generator are available in the Github Container Registry
```
docker pull docker.pkg.github.com/commercetools/rmf-codegen/codegen:latest
```
## Usage
General Usage:
```
Usage: rmf-codegen [-hv] [COMMAND]
Allows to validate RAML files and generate code from them
-h, --help display this help message
-v, --version print version information and exit
Commands:
generate Generate source code from a RAML specification.
verify Allows to verify if a raml spec is valid.
validate Validate the raml spec against defined rules and generate a validation report.
```
Generating Client SDKs or normalized RAML for documentation:
```
Usage: rmf-codegen generate [-hvw] [-b=]
[-c=] [-m=]
-o= [-s=] -t=
Generate source code from a RAML specification.
Api file location
-b, --base-package=
The base package, this package in case the model or
client models aren't provided
-c, --client-package=
The client package, This will be used as the package
for the client stub.
-h, --help display this help message
-m, --model-package=
The models package, this will be used as the model
package in the generated code.
-o, --output-folder=
Output folder for generated files.
-s, --shared-package=
The shared package to be used for the generated code.
-t, --target= Specifies the code generation target
Valid values: JAVA_CLIENT, TYPESCRIPT_CLIENT,
CSHARP_CLIENT, PHP_CLIENT, PHP_BASE, PHP_TEST,
POSTMAN, RAML_DOC
-v, --verbose If set, this would move the verbosity level to debug.
-w, --watch Watches the files for changes
```
Verifying a RAML API:
```
Usage: rmf-codegen verify [-hw]
Allows to verify if a RAML spec is valid.
Api file location
-h, --help display this help message
-w, --watch Watches the files for changes
```
Validating a RAML API and generating a validity report:
```
Usage: validate [-hvw] [--list-rules] [-f=]
[-l=] [-lf=]
[-o=] [-r=]
[-s=] [-t=]
Allows to verify if a raml spec is valid according to CT guidelines and generates a validation report
Api file location
-f, --format= Specifies the output format. Valid values: CLI, JSON, MARKDOWN
-h, --help display this help message
-l, --link-base=
-lf, --link-format= Specifies the link format. Valid values: CLI, GITHUB
--list-rules Show all rules
-o, --outputTarget=
-r, --ruleset= Ruleset configuration
-s, --severity= Diagnostic severity. Valid values: info, warn, error
-t, --temp= Temporary folder
-v, --verbose Verbose
-w, --watch Watches the files for changes
```
## Development
### Build the "fat jar"
A single "fat jar" is built with the following commands:
```sh
cd tools/cli-application/
../../gradlew build
```
The JAR can then be found at `./rmf-codegen.jar`
### Build a native executable with GraalVM
A native executable is built with the following commands:
```sh
cd tools/cli-application/
../../gradlew nativeImage
```
The native executable can then be found at `./tools/cli-application/build/graal/rmf-codegen`.
It's currently only tested with Mac OS X. It emits error messages but the functionality works.
### Why did we choose kotlin for writing our code generators?
We choose kotlin because of the following features:
- extension methods, which allow us to add methods to our RMF model types
- multi-line template string with embedded expressions, which allows us to keep the templates and the code in the same file
- it integrates very well with our RMF Java types
- it has very good IDE support, which makes writing code generators very easy
These features help in developing code generators for different programming languges/frameworks.
# Running tests against your own RAML files
Our `TestCodeGenerator` test can be run against a user provided RAML file by setting
the `TEST_RAML_FILE` environment variable to the file path.