mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-17 04:24:35 +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
65 lines
2.9 KiB
Haskell
65 lines
2.9 KiB
Haskell
-- | We are in the process of building DTO types incrementally. We use
|
|
-- placeholder types in positions in data structures that are not fully-defined
|
|
-- yet. For example 'PlaceholderObject' represents some unspecified JSON object,
|
|
-- and 'PlaceholderArray' represents an array whose contents are not yet
|
|
-- specified.
|
|
--
|
|
-- We are transitioning from converting 'Hasura.RQL.Types.Metadata' directly to
|
|
-- JSON to converting it to 'Hasura.Server.API.DTO.Metadata.MetadataDTO'
|
|
-- instead. Serialization and deserialization for placeholder values is
|
|
-- delegated to the old JSON serialization code.
|
|
module Hasura.Metadata.DTO.Placeholder
|
|
( PlaceholderArray (..),
|
|
PlaceholderObject (..),
|
|
IsPlaceholder (..),
|
|
)
|
|
where
|
|
|
|
import Autodocodec (Autodocodec, HasCodec (codec), codecViaAeson, dimapCodec, valueCodec, vectorCodec, (<?>))
|
|
import Autodocodec.OpenAPI ()
|
|
import Data.Aeson (FromJSON, ToJSON)
|
|
import Data.Aeson qualified as JSON
|
|
import Data.OpenApi qualified as OpenApi
|
|
import Hasura.Prelude
|
|
|
|
-- | Stands in for an array that we have not had time to fully specify yet.
|
|
-- Generated OpenAPI documentation for 'PlaceholderArray' will permit an array
|
|
-- of values of any type, and a note will be appended to the documentation
|
|
-- string for the value explaining that this is a temporary placeholder.
|
|
newtype PlaceholderArray = PlaceholderArray JSON.Array
|
|
deriving newtype (Show, Eq, FromJSON, ToJSON)
|
|
deriving stock (Generic)
|
|
deriving (OpenApi.ToSchema) via (Autodocodec PlaceholderArray)
|
|
|
|
-- | Stands in for an object that we have not had time to fully specify yet.
|
|
-- Generated OpenAPI documentation for 'PlaceholderObject' will permit an object
|
|
-- with any keys with any types of values. A note will be appended to the
|
|
-- documentation string for the value explaining that this is a temporary
|
|
-- placeholder.
|
|
newtype PlaceholderObject = PlaceholderObject JSON.Object
|
|
deriving newtype (Show, Eq, FromJSON, ToJSON)
|
|
deriving stock (Generic)
|
|
deriving (OpenApi.ToSchema) via (Autodocodec PlaceholderObject)
|
|
|
|
instance HasCodec PlaceholderArray where
|
|
codec = dimapCodec mapOutput mapInput (vectorCodec valueCodec) <?> documentation
|
|
where
|
|
mapOutput = PlaceholderArray
|
|
mapInput (PlaceholderArray a) = a
|
|
documentation =
|
|
"\n\narray of values of unspecified type - this is a placeholder that will eventually be replaced with a more detailed description"
|
|
|
|
instance HasCodec PlaceholderObject where
|
|
codec = codecViaAeson "\n\nobject with unspecified properties - this is a placeholder that will eventually be replaced with a more detailed description"
|
|
|
|
class IsPlaceholder p a | a -> p where
|
|
-- | Use this function to mark an Aeson type (Array or Object) as
|
|
-- a temporary placeholder in a larger data structure.
|
|
placeholder :: a -> p
|
|
|
|
instance IsPlaceholder PlaceholderArray JSON.Array where
|
|
placeholder = PlaceholderArray
|
|
|
|
instance IsPlaceholder PlaceholderObject JSON.Object where
|
|
placeholder = PlaceholderObject
|