mirror of
https://github.com/NorfairKing/autodocodec.git
synced 2024-09-11 14:36:05 +03:00
2.7 KiB
2.7 KiB
Autodocodec
Autodocodec is short for "self(auto)- documenting encoder and decoder".
In short: You write one (1) instance, of the 'Codec' type-class, for your type, and you get:
- A 'ToJSON' instance from 'aeson'
- A 'FromJSON' instance from 'aeson'
- A json schema
- A human-readable yaml schema
- Hopefully soon also: A swagger schema
- Hopefully soon also: An openapi schema
- Potentially also: bson instances for mongodb
DISCLAIMER: This is a work in progress.
This is not ready for production, it is not in use in any of my own projects yet, I do not recommend using it yet.
- Documentation is not complete.
- Some pieces of the implementation
Goals:
- Correct-by-construction encoding and decoding, without generating code.
- Generate automatically-correct documentation from code.
- Fun but not important: Be able to provide instances without depending on aeson and/or yaml.
- Would be nice: support for recursive types.
Fully featured example
TODO
Tests
While we don't provide any actual guarantees, we do have tests for the following properties that we would like to maintain:
- Encoding and decoding roundtrips.
- For standard types, encoding behaves in the same way that
aeson
does. - Error messages for decoding are still good.
- Generated Human-readible documentation looks good.
- Generated JSON schemas look good.
- Generated Swagger schemas look good.
- Generated OpenAPI schemas look good.
- Generated values are accepted by the corresponding generated JSON schemas.
- Generated values are accepted by the corresponding generated Swagger schemas.
- Generated values are accepted by the corresponding generated OpenAPI schemas.
- We try to make sure that backward compatibility is maintained.
- Codecs are more or less inspectable.
- TODO: Encoding and decoding is still fast