mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-24 16:03:37 +03:00
2f3ae93ab0
This implements an initial set of DTO types that represent serialized metadata. These new types come with codecs using autodocodec which are used to derive both JSON serialization, and OpenAPI documentation. This ensures that we can automatically generate API documentation that is guaranteed to match JSON produced by the server. For the moment the new types are not used for anything except to generate an early version of an OpenAPI document. Because this is early work the DTO types for each metadata format version list top-level properties only with placeholders for the types of each top-level property. This early iteration demonstrates using a sum type in Haskell that maps to a tagged union in OpenAPI (using the `version` field value as a tag). This work is experimental and incomplete! Please do not incorporate the generated OpenAPI documentation into essential workflows at this time. PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4801 GitOrigin-RevId: d2f110a6237b73520cdba24667333ef14e8cdd3d
58 lines
2.2 KiB
Haskell
58 lines
2.2 KiB
Haskell
module Hasura.Metadata.DTO.Metadata (MetadataDTO (..)) where
|
|
|
|
import Autodocodec
|
|
( Autodocodec (Autodocodec),
|
|
HasCodec (codec),
|
|
JSONCodec,
|
|
dimapCodec,
|
|
disjointEitherCodec,
|
|
named,
|
|
(<?>),
|
|
)
|
|
import Autodocodec.OpenAPI ()
|
|
import Data.Aeson (FromJSON, ToJSON)
|
|
import Data.OpenApi qualified as OpenApi
|
|
import Hasura.Metadata.DTO.MetadataV1 (MetadataV1)
|
|
import Hasura.Metadata.DTO.MetadataV2 (MetadataV2)
|
|
import Hasura.Metadata.DTO.MetadataV3 (MetadataV3)
|
|
import Hasura.Prelude
|
|
|
|
-- | Exported representation of the GraphQL Engine metadata configuration
|
|
-- format.
|
|
--
|
|
-- The OpenAPI specification for metadata is experimental and incomplete. Please
|
|
-- do not incorporate it into essential workflows at this time.
|
|
data MetadataDTO = V1 MetadataV1 | V2 MetadataV2 | V3 MetadataV3
|
|
deriving stock (Show, Eq, Generic)
|
|
deriving (FromJSON, ToJSON, OpenApi.ToSchema) via (Autodocodec MetadataDTO)
|
|
|
|
-- | Sum types translate to union types in OpenApi documents via
|
|
-- `disjointEitherCodec` (or via `eitherCodec` if the encoded JSON is not
|
|
-- necessarily disjoint). In this case we ensure that the encodings of
|
|
-- 'MetadataV1', 'MetadataV2', and 'MetadataV3' are disjoint by using
|
|
-- 'versionField' in the codec for each variant which injects a field into the
|
|
-- JSON representation that requires a specific number to parse successfully.
|
|
-- ('MetadataV1' is the only variant where the version field is optional.)
|
|
--
|
|
-- A codec that represents more than two variants of different types requires
|
|
-- nesting `disjointEitherCodec`. Thankfully in the generated OpenApi
|
|
-- documentation these three variants are flattened into a single @oneOf@ list
|
|
-- of allowed schemas.
|
|
instance HasCodec MetadataDTO where
|
|
codec =
|
|
named "Metadata" $
|
|
dimapCodec decode encode $
|
|
disjointEitherCodec
|
|
(codec :: JSONCodec MetadataV1)
|
|
( disjointEitherCodec
|
|
(codec :: JSONCodec MetadataV2)
|
|
(codec :: JSONCodec MetadataV3)
|
|
)
|
|
<?> "configuration format for the Hasura GraphQL Engine"
|
|
where
|
|
decode = either V1 $ either V2 V3
|
|
encode = \case
|
|
V1 v1 -> Left v1
|
|
V2 v2 -> Right $ Left v2
|
|
V3 v3 -> Right $ Right v3
|