Autodocodec
Autodocodec is short for "self(auto)- documenting encoder and decoder".
In short: You write a single instance, of the 'Codec' type-class, for your type, and you get:
- A 'ToJSON' instance from 'aeson' with both a
toJSONandtoEncodingimplementation - A 'FromJSON' instance from 'aeson'
- A 'ToYaml' instance from 'yaml'
- A json schema
- A nicely-coloured human-readable yaml schema
- A Swagger schema
- An Openapi schema
See the golden test directory directory for example outputs.
Features
- β Correct-by-construction encoding and decoding, without generating code.
- β Generate automatically-correct documentation from code.
- β Support for recursive types.
State of this project
This project is ready to try out!
Fully featured example
{-# 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
data Example = Example
{ exampleTextField :: !Text,
exampleIntField :: !Int
}
deriving stock (Show, Eq, Generic)
deriving
( FromJSON, -- <- FromJSON instance for free.
ToJSON -- <- ToJSON instance 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
main :: IO ()
main = do
let schema = T.unpack $ renderColouredSchemaViaCodec @Example
putStrLn schemaThis 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
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 through JSON.
- For standard types, encoding behaves in the same way that
aesondoes. - 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.
- Encoding and decoding roundtrips through YAML.
- We try to make sure that backward compatibility is maintained.
- Codecs are more or less inspectable.
- Encoding and decoding is still fast