mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-16 18:42:30 +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
49 lines
3.0 KiB
Haskell
49 lines
3.0 KiB
Haskell
module Hasura.Metadata.DTO.MetadataV3 (MetadataV3 (..)) where
|
|
|
|
import Autodocodec (Autodocodec (Autodocodec), HasCodec (codec), object, optionalField, requiredField, (.=))
|
|
import Autodocodec.OpenAPI ()
|
|
import Data.Aeson (FromJSON, ToJSON)
|
|
import Data.OpenApi qualified as OpenApi
|
|
import Hasura.Metadata.DTO.Placeholder (PlaceholderArray, PlaceholderObject)
|
|
import Hasura.Metadata.DTO.Utils (versionField)
|
|
import Hasura.Prelude
|
|
|
|
-- | Revision 3 of the Metadata export format. Note that values of the types,
|
|
-- 'PlaceholderArray' and 'PlaceholderObject' are placeholders that will
|
|
-- eventually be expanded to represent more detail.
|
|
data MetadataV3 = MetadataV3
|
|
{ metaV3Actions :: Maybe PlaceholderArray,
|
|
metaV3Allowlist :: Maybe PlaceholderArray,
|
|
metaV3ApiLimits :: Maybe PlaceholderObject,
|
|
metaV3CronTriggers :: Maybe PlaceholderArray,
|
|
metaV3CustomTypes :: Maybe PlaceholderObject,
|
|
metaV3InheritedRoles :: Maybe PlaceholderArray,
|
|
metaV3QueryCollections :: Maybe PlaceholderArray,
|
|
metaV3RemoteSchemas :: Maybe PlaceholderArray,
|
|
metaV3RestEndpoints :: Maybe PlaceholderArray,
|
|
metaV3Sources :: PlaceholderArray
|
|
}
|
|
deriving stock (Show, Eq, Generic)
|
|
deriving (FromJSON, ToJSON, OpenApi.ToSchema) via (Autodocodec MetadataV3)
|
|
|
|
-- | Codecs simultaneously provide serialization logic for a type, and
|
|
-- documentation. A codec can be used to generate a specification in OpenAPI or
|
|
-- another format that matches the JSON serialization of the same type.
|
|
-- Documentation strings (the second argument to 'optionalField' and to
|
|
-- 'requiredField') appear in the generated specification for users' reference.
|
|
instance HasCodec MetadataV3 where
|
|
codec =
|
|
object "MetadataV3" $
|
|
MetadataV3
|
|
<$ versionField 3
|
|
<*> optionalField "actions" "action definitions which extend Hasura's schema with custom business logic using custom queries and mutations" .= metaV3Actions
|
|
<*> optionalField "allowlist" "safe GraphQL operations - when allow lists are enabled only these operations are allowed" .= metaV3Allowlist
|
|
<*> optionalField "api_limits" "limts to depth and/or rate of API requests" .= metaV3ApiLimits
|
|
<*> optionalField "cron_triggers" "reliably trigger HTTP endpoints to run custom business logic periodically based on a cron schedule" .= metaV3CronTriggers
|
|
<*> optionalField "custom_types" "custom type definitions" .= metaV3CustomTypes
|
|
<*> optionalField "inherited_roles" "an inherited role is a way to create a new role which inherits permissions from two or more roles" .= metaV3InheritedRoles
|
|
<*> optionalField "query_collections" "group queries using query collections" .= metaV3QueryCollections
|
|
<*> optionalField "remote_schemas" "merge remote GraphQL schemas and provide a unified GraphQL API" .= metaV3RemoteSchemas
|
|
<*> optionalField "rest_endpoints" "REST interfaces to saved GraphQL queries and mutations" .= metaV3RestEndpoints
|
|
<*> requiredField "sources" "configured databases" .= metaV3Sources
|