2021-10-20 18:59:50 +03:00
# Autodocodec
Autodocodec is short for "self(auto)- documenting encoder and decoder".
2021-10-30 13:03:59 +03:00
In short:
2021-11-06 14:17:40 +03:00
You write a single instance, of the 'Codec' type-class, for your type, and you get:
2021-10-30 13:03:59 +03:00
2021-11-11 15:45:40 +03:00
* [A 'ToJSON' instance from 'aeson' with both a `toJSON` and `toEncoding` implementation ](https://hackage.haskell.org/package/aeson-2.0.1.0/docs/Data-Aeson-Types.html#t:ToJSON )
2021-10-30 13:03:59 +03:00
* [A 'FromJSON' instance from 'aeson' ](https://hackage.haskell.org/package/aeson-2.0.1.0/docs/Data-Aeson-Types.html#t:FromJSON )
2022-11-08 10:24:31 +03:00
* [A 'ToYaml' instance from 'yaml' ](https://hackage.haskell.org/package/yaml-0.11.7.0/docs/Data-Yaml-Builder.html#t:ToYaml )
2021-10-30 13:03:59 +03:00
* [A json schema ](http://json-schema.org/ )
2021-11-06 14:17:40 +03:00
* [A nicely-coloured human-readable yaml schema ](./autodocodec-yaml )
* [A Swagger schema ](https://swagger.io/specification/v2/ )
* [An Openapi schema ](https://swagger.io/specification/ )
2021-10-30 13:03:59 +03:00
2021-11-06 14:17:40 +03:00
See [the golden test directory ](./autodocodec-api-usage/test_resources ) directory for example outputs.
2021-10-30 13:03:59 +03:00
2021-11-06 14:17:40 +03:00
## Features
2021-10-30 13:03:59 +03:00
2021-11-06 14:17:40 +03:00
* ✓ Correct-by-construction encoding and decoding, without generating code.
* ✓ Generate automatically-correct documentation from code.
* ✓ Support for recursive types.
2021-10-30 13:03:59 +03:00
2021-11-06 14:17:40 +03:00
## State of this project
2021-10-20 18:59:50 +03:00
2021-11-06 14:17:40 +03:00
This project is ready to try out!
2021-10-30 13:03:59 +03:00
2021-11-01 16:26:27 +03:00
## Fully featured example
2021-11-06 14:17:40 +03:00
``` haskell
data Example = Example
{ exampleTextField :: !Text,
exampleIntField :: !Int
}
deriving stock (Show, Eq, Generic)
deriving
( FromJSON, -- < - FromJSON instance for free .
ToJSON, -- < - ToJSON instance for free .
Swagger.ToSchema, -- < - Swagger schema for free .
OpenAPI.ToSchema -- < - OpenAPI schema for free .
)
via (Autodocodec Example)
instance HasCodec Example where
codec =
object "Example" $
Example
< $> requiredField "text" "documentation for the text field" .= exampleTextField
< *> requiredField "int" "documentation for the int field" .= exampleIntField
```
2021-11-01 16:26:27 +03:00
2021-11-06 14:11:42 +03:00
## Tests
While we don't provide any actual guarantees, we do have tests for the following properties that we would like to maintain:
2021-11-11 15:24:38 +03:00
* [Encoding and decoding roundtrips through JSON. ](./autodocodec-api-usage/test/Autodocodec/AesonSpec.hs )
2021-11-06 14:11:42 +03:00
* [For standard types, encoding behaves in the same way that `aeson` does. ](./autodocodec-api-usage/test/Autodocodec/AesonSpec.hs )
* [Error messages for decoding are still good. ](./autodocodec-api-usage/test/Autodocodec/AesonSpec.hs )
* [Generated Human-readible documentation looks good. ](./autodocodec-api-usage/test/Autodocodec/Yaml/DocumentSpec.hs )
* [Generated JSON schemas look good. ](./autodocodec-api-usage/test/Autodocodec/Aeson/SchemaSpec.hs )
* [Generated Swagger schemas look good. ](./autodocodec-api-usage/test/Autodocodec/SwaggerSpec.hs )
* [Generated OpenAPI schemas look good. ](./autodocodec-api-usage/test/Autodocodec/OpenAPISpec.hs )
* [Generated values are accepted by the corresponding generated JSON schemas. ](./autodocodec-api-usage/test/Autodocodec/Aeson/SchemaSpec.hs )
* [Generated values are accepted by the corresponding generated Swagger schemas. ](./autodocodec-api-usage/test/Autodocodec/SwaggerSpec.hs )
* [Generated values are accepted by the corresponding generated OpenAPI schemas. ](./autodocodec-api-usage/test/Autodocodec/OpenAPISpec.hs )
2021-11-11 15:24:38 +03:00
* [Encoding and decoding roundtrips through YAML. ](./autodocodec-api-usage/test/Autodocodec/YamlSpec.hs )
2021-11-06 14:11:42 +03:00
* [We try to make sure that backward compatibility is maintained. ](./autodocodec-api-usage/src/Autodocodec/Usage.hs )
* [Codecs are more or less inspectable. ](./autodocodec-api-usage/test/Autodocodec/ShowSpec.hs )
2021-11-17 16:39:36 +03:00
* [Encoding and decoding is still fast ](./autodocodec-api-usage/bench/Main.hs )