search

biocad / openapi3

OpenAPI 3.0 data model
BSD 3-Clause "New" or "Revised" License
39 stars 53 forks source link

Why are the schemas different for `ToParamSchema UUID` and `ToSchema UUID` #94

Open sir4ur0n opened 6 months ago

sir4ur0n commented 6 months ago

Hello,

While writing manual OpenApi instances for a phantom type wrapping UUID today, I noticed that (undeclare (declareNamedSchema (Proxy @UUID)))._namedSchemaSchema /= toParamSchema (Proxy @UUID), which I find surprising (not just for UUID but for any type).

instance ToParamSchema UUID where
  toParamSchema _ = mempty
    & type_ ?~ OpenApiString
    & format ?~ "uuid"

instance ToSchema UUID.UUID where
  declareNamedSchema p = pure $ named "UUID" $ paramSchemaToSchema p
    & example ?~ toJSON (UUID.toText UUID.nil)

Is there a reason why the example is only for ToSchema and not for ToParamSchema? That looks like a bug to me.

I would expect the implementation to be

instance ToParamSchema UUID where
  toParamSchema _ = mempty
    & type_ ?~ OpenApiString
    & format ?~ "uuid"
    & example ?~ toJSON (UUID.toText UUID.nil)

instance ToSchema UUID.UUID where
  declareNamedSchema p = pure $ named "UUID" $ paramSchemaToSchema p

More generally, is there a scenario where (undeclare (declareNamedSchema (Proxy @a)))._namedSchemaSchema /= toParamSchema (Proxy @a) makes sense for any type a?