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
2023-06-01 19:08:04 +03:00
{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE DerivingVia #-}
{-# LANGUAGE TypeApplications #-}
module Main (main) where
import Autodocodec
import Autodocodec.Yaml
import GHC.Generics
import Data.Aeson (FromJSON, ToJSON)
import Data.Text (Text)
import qualified Data.Text as T
2021-11-06 14:17:40 +03:00
data Example = Example
{ exampleTextField :: !Text,
exampleIntField :: !Int
}
deriving stock (Show, Eq, Generic)
deriving
( FromJSON, -- < - FromJSON instance for free .
2023-06-01 19:08:04 +03:00
ToJSON -- < - ToJSON instance for free .
2021-11-06 14:17:40 +03:00
)
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
2023-06-01 19:08:04 +03:00
main :: IO ()
main = do
let schema = T.unpack $ renderColouredSchemaViaCodec @Example
putStrLn schema
```
This will output a nice coloured yaml-schema:
```
# Example
text: # required
# documentation for the text field
< string >
int: # required
# documentation for the int field
< number > # between -9223372036854775808 and 9223372036854775807
2021-11-06 14:17:40 +03:00
```
2023-06-01 19:08:04 +03:00
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 )