Amper
Amper (Api MaPpER) is a CLI that generates files for building an API wrapper in Crystal, based on a sample JSON file.
Any null values within the sample JSON file will cause AMPER to exit with an error, as it will be unable to determine the type for that key.
Installation
TODO Write installation instructions here
Usage
The most basic usage of amper is the name of the generated class, including any enclosing modules (in camel case), and the location of the example JSON file.
$ amper Wrapper::Foo "test/files/foo.json"
This will generate a file called foo.cr within the src folder, based on the structure of the specified json file. If you wish to give the file a different name or location, you can use the -c flag, as so:
$ amper Foo "test/files/foo.json" -c "src/bar/foo.cr"
Other options include the -t flag to generate a test file, or a -s flag to generate a spec file.
NOTE: Test files are generated based on the minitest.cr shard, which must be added to your shard.yml file.
$ amper Foo "test/files/foo.json" -s
This command generates a spec file located at spec/foo_spec.cr. The location and filename can be customized by providing the file path immediately after the -s flag.
$ amper Foo "test/files/foo.json" -t
This command generates a spec file located at test/foo_test.cr. As with the spec flag, you can also provide a custom file path for the generated file.
Limitations
There are some limitations to Amper, so it's important to look through the code generated, before publishing/using it.
- Time strings and Unix Epoch integers will be read as such, instead of being added as a Time class. If your JSON does include time, this change will have to be made manually, after the code is generated.
- If the source JSON includes nested objects, then the key of that object will be used to generate a class name. Developers, of course, may change these names afterwards.
- If the source JSON includes an array of objects, the class will be given a placeholder name of NestedClass with an autoincrementing integer suffix, due to there being no key to generate a class name from.
- If the objects in the abovementioned case have individual variations, then Amper will base the object on the first item, and ignore variations of other objects in the array.
- If an array is composed of different types of values, such as integers, floats, and strings, then the type in the generated code will be a union type.
- If an array contains mixed types, such as objects, arrays, and simple values, then it isn't guaranteed to work. I've neve seen this in an API, so I haven't written any code to handle it's possibility.
Development
TODO
- Add test generators.
- Add spec generators.
- Combine arrays of objects into a single object with union types to allow for variations.
Contributing
- Fork it (https://codeberg.org/HCLarsen/amper/forks)
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
Contributors
- Chris Larsen - creator and maintainer