Code Examples Generator

The purpose of this project is to create a command line tool that is able to parse Platform of Trust API documentation and examples from RAML 1.0 files and generate example HTTP requests in various languages.

For instructions how to use this tool see USER GUIDE.

See also Code Examples Validator and implementation (.travis.yml) in the PlatformOfTrust/docs repository.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

This is a Clojure project and requires:

Java 8 or above
Leiningen 2.0 or above (OSX users can use brew install leiningen).

You can make sure that everything is installed by running java --version && lein -v.

$ java --version && lein -v
java 11.0.2 2018-10-16 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.2+7-LTS)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.2+7-LTS, mixed mode)
Leiningen 2.9.1 on Java 11.0.2 Java HotSpot(TM) 64-Bit Server VM

Running the application

lein run will run the code example generator (and install dependencies). Without passing any extra parameters it will display command line help.

 $lein run
  -s, --source PATH                     Required RAML file or a directory that contains RAML files.
  -d, --dest PATH      ./pot-examples   Optional Directory for generated code examples.
  -H, --host HOST      api.oftrust.net  Optional URI host.
  -S, --scheme SCHEME  https            Optional URI scheme (`https` or `http`).
  -h, --help
  -v, --version

See user guide for more details how to use it.

Testing

lein test                               # Run unit tests
lein test-refesh                        # Run unit tests automatically when files change
lein cloverage                          # Generate code coverage report

NB! This project is expected to have > 50% code coverage for unit tests and it has been set as a criteria for successful builds in CI. You can change it in project.clj.

  :cloverage {:fail-threshold 50
              :low-watermark 70
              :high-watermark 90}

e2e tests

You can run generated code examples against mockbin.org to validatate whether examples are semantically correct e.g. there are no typos and code examples are valid examples for their respective languages.

  sh ./scripts/generate_examples.sh     # Generate code examples
  npm install unirest                   # Install unirest
  sh ./scripts/e2e_tests/nodejs.sh      # Test node.js/unirest examples 
  sh ./scripts/e2e_tests/python.sh      # Test Python examples
  sh ./scripts/e2e_tests/curl.sh        # Test cURL examples

NB! When running node.js tests locally a path to installed node_modules needs to be provided. This the path where npm install unirest was triggered.

NODE_PATH=/Users/sven/dev/PlatformOfTrust/code-examples-generator/node_modules ./scripts/e2e_tests/nodejs.sh

Deployment

Each commit to master branch will trigger a new build process that will build a binary (jar file raml2http.jar) that will be uploaded to the assets of latest release.

Each tag will create a release with tag name and upload jar file with version suffix e.g. raml2http-v1.0.1.jar.

Development flow

Create a feature branch. Implement changes. Test.
Update e2e test if adding new templates (see .travis.yml).
Bump the version in project.clj
Update Change Log.
Merge feature/bugifix branch to master
Create a new release. This will trigger a new build in CI which will upload a new jar file e.g. raml2http-v1.0.1.jar to release assests in a few minutes.

Contributing

You might want to...

Follow The Clojure Style Guide for consistency.
Commit and create PRs using Conventional Commits standard.
Use SemVer.
Update Change Log.

lein eastwood                           # Linter
lein kibit                              # Static code analyzer
lein bikeshed                           # Gives tips for writing better code
lein ancient                            # Check for outdated dependencies
lein annotations                        # Display all comment annotations (TODO, FIXME etc.)

Acknowledgements/future improvements

This project does not support parsing all the options according to RAML 1.0 spec. There are too many nuances and options that did not fit the scope of this project.

Some examples:

This tool currently supports only single examples for responses and Types.
...

License

This project is licensed under the MIT License - see the LICENSE file for details.