Merge pull request #35 from biocad/maksbotan/with-description-unique

version 0.1.3.15 WithDescription unique for fields

Author: maksbotan

CHANGELOG.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.3.15] - 2023-11-20
+### Changed
+- `WithDescription` does not clash between different fields with the same type.
+
 ## [0.1.3.14] - 2023-06-14
 ### Added
 - Debug log formatter `debugLogHandler`, customizable log middleware `logMiddlewareCustom`.

cabal.project

@@ -8,6 +8,7 @@ source-repository-package
   type: git
   location: https://github.com/biocad/bcd-log
   tag: 16808faa4db0d3d94ff4006c5ca88691551ebe40
+  --sha256: E/VW3Xb7Nvefle2QkTckuWn8QB2YhbBCEBVO2y/xcbo=
 
 source-repository-package
   type: git

src/Web/Template/Servant/Swagger.hs

@@ -9,8 +9,9 @@ module Web.Template.Servant.Swagger
 
 import Control.Lens                 (_Just, (%~), (&), (?~))
 import Data.Aeson                   (FromJSON, ToJSON, Value (..))
-import Data.OpenApi                 (ToSchema (..), defaultSchemaOptions, description, enum_,
-                                     genericDeclareNamedSchema, schema)
+import Data.OpenApi                 (NamedSchema (..), Referenced (..), ToSchema (..),
+                                     declareSchemaRef, defaultSchemaOptions, description, enum_,
+                                     genericDeclareNamedSchema, oneOf, schema)
 import Data.OpenApi.Internal.Schema (GToSchema, rename)
 import Data.Override                (Override)
 import Data.Override.Aeson          ()
@@ -47,8 +48,24 @@ newtype WithDescription (descr :: Symbol) a
 
 instance (Typeable a, KnownSymbol descr, ToSchema a) => ToSchema (WithDescription descr a) where
   declareNamedSchema _ = do
-    sch <- declareNamedSchema @a Proxy
-    return $ sch & schema . description ?~ pack (symbolVal @descr Proxy)
+    -- Different fields may use the same type with different descriptions.
+    -- To support this we use a hack: generate schema for a type, and
+    -- wrap it for specific field with 'oneOf' with exactly one option, adding
+    -- concrete description.
+    --
+    -- Schema for a field with description should be unnamed, to prevent it
+    -- from reusage in other fields.
+    --
+    -- OpenAPI 3.1 will have a mechanism for this without hacks, but we use 3.0.
+    sch <- declareSchemaRef @a Proxy
+    case sch of
+      -- If schema for a field is something simple like "type: string",
+      -- add description directly to it. It won't be shared with other fields.
+      Inline sub -> return $ NamedSchema Nothing $ sub
+        & description ?~ pack (symbolVal @descr Proxy)
+      Ref ref -> return $ NamedSchema Nothing $ mempty
+        & description ?~ pack (symbolVal @descr Proxy)
+        & oneOf ?~ [Ref ref]
 
 -- | Describe possible enumeration values for a 'Text' field.
 --

web-template.cabal

@@ -1,5 +1,5 @@
 name:                web-template
-version:             0.1.3.14
+version:             0.1.3.15
 synopsis:            Web template
 description:
             Web template includes:
@@ -67,7 +67,8 @@ library
                      , openapi3 >= 3.2.0
                      , openid-connect >= 0.1.1
                      , resourcet
-                     , scotty
+                     -- 0.20 has breaking changes
+                     , scotty < 0.20
                      , servant >= 0.18
                      , servant-openapi3
                      , servant-server >= 0.18