mirror of
https://github.com/NorfairKing/autodocodec.git
synced 2024-08-16 18:00:32 +03:00
self(auto)- documenting encoders and decoders
|
||
---|---|---|
.github | ||
autodocodec | ||
autodocodec-api-usage | ||
autodocodec-openapi3 | ||
autodocodec-schema | ||
autodocodec-servant-multipart | ||
autodocodec-swagger2 | ||
autodocodec-yaml | ||
nix | ||
.gitignore | ||
.hlint.yaml | ||
ci.nix | ||
default.nix | ||
LICENSE | ||
README.md | ||
shell.nix | ||
stack.yaml | ||
TODO.smos |
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
toJSON
andtoEncoding
implementation - 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
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
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
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.
- 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