WPB-4240: Migrate from swagger2 to openapi3 (#3570)

---------

Co-authored-by: Igor Ranieri Elland <[email protected]>
Co-authored-by: Igor Ranieri <[email protected]>

Author: lepsa

changelog.d/4-docs/WPB-4240

@@ -0,0 +1 @@
+Updating the route documentation from Swagger 2 to OpenAPI 3.

changelog.d/5-internal/WPB-4240

@@ -0,0 +1,4 @@
+Updating the route documentation library from swagger2 to openapi3.
+
+This also introduced a breaking change in how we track what federation calls each route makes.
+The openapi3 library doesn't support extension fields, and as such tags are being used instead in a similar way.

libs/brig-types/brig-types.cabal

@@ -156,8 +156,8 @@ test-suite brig-types-tests
     , brig-types
     , bytestring-conversion  >=0.3.1
     , imports
+    , openapi3
     , QuickCheck             >=2.9
-    , swagger2               >=2.5
     , tasty
     , tasty-hunit
     , tasty-quickcheck

libs/brig-types/default.nix

@@ -13,8 +13,8 @@
 , gitignoreSource
 , imports
 , lib
+, openapi3
 , QuickCheck
-, swagger2
 , tasty
 , tasty-hunit
 , tasty-quickcheck
@@ -47,8 +47,8 @@ mkDerivation {
     base
     bytestring-conversion
     imports
+    openapi3
     QuickCheck
-    swagger2
     tasty
     tasty-hunit
     tasty-quickcheck

libs/brig-types/test/unit/Test/Brig/Roundtrip.hs

@@ -20,7 +20,7 @@ module Test.Brig.Roundtrip where
 import Data.Aeson (FromJSON, ToJSON, parseJSON, toJSON)
 import Data.Aeson.Types (parseEither)
 import Data.ByteString.Conversion
-import Data.Swagger (ToSchema, validatePrettyToJSON)
+import Data.OpenApi (ToSchema, validatePrettyToJSON)
 import Imports
 import Test.Tasty (TestTree)
 import Test.Tasty.QuickCheck (Arbitrary, counterexample, testProperty, (.&&.), (===))
@@ -40,7 +40,7 @@ testRoundTrip = testProperty msg trip
 
 testRoundTripWithSwagger ::
   forall a.
-  (Arbitrary a, Typeable a, ToJSON a, FromJSON a, ToSchema a, Eq a, Show a) =>
+  (Arbitrary a, ToJSON a, FromJSON a, ToSchema a, Eq a, Show a) =>
   TestTree
 testRoundTripWithSwagger = testProperty msg (trip .&&. scm)
   where

libs/deriving-swagger2/default.nix

@@ -8,12 +8,12 @@
 , gitignoreSource
 , imports
 , lib
-, swagger2
+, openapi3
 }:
 mkDerivation {
   pname = "deriving-swagger2";
   version = "0.1.0";
   src = gitignoreSource ./.;
-  libraryHaskellDepends = [ base extra imports swagger2 ];
+  libraryHaskellDepends = [ base extra imports openapi3 ];
   license = lib.licenses.agpl3Only;
 }

libs/deriving-swagger2/deriving-swagger2.cabal

@@ -62,9 +62,9 @@ library
     -Wredundant-constraints -Wunused-packages
 
   build-depends:
-      base      >=4   && <5
+      base      >=4 && <5
     , extra
     , imports
-    , swagger2  >=0.6
+    , openapi3
 
   default-language:   GHC2021

libs/deriving-swagger2/src/Deriving/Swagger.hs

@@ -1,3 +1,5 @@
+{-# LANGUAGE RankNTypes #-}
+
 -- This file is part of the Wire Server implementation.
 --
 -- Copyright (C) 2022 Wire Swiss GmbH <[email protected]>
@@ -22,10 +24,10 @@ module Deriving.Swagger where
 import Data.Char qualified as Char
 import Data.Kind (Constraint)
 import Data.List.Extra (stripSuffix)
+import Data.OpenApi.Internal.Schema (GToSchema)
+import Data.OpenApi.Internal.TypeShape
+import Data.OpenApi.Schema
 import Data.Proxy (Proxy (..))
-import Data.Swagger (SchemaOptions, ToSchema (..), constructorTagModifier, defaultSchemaOptions, fieldLabelModifier, genericDeclareNamedSchema)
-import Data.Swagger.Internal.Schema (GToSchema)
-import Data.Swagger.Internal.TypeShape (TypeHasSimpleShape)
 import GHC.Generics (Generic (Rep))
 import GHC.TypeLits (ErrorMessage (Text), KnownSymbol, Symbol, TypeError, symbolVal)
 import Imports
@@ -81,6 +83,7 @@ import Imports
 -- | A newtype wrapper which gives ToSchema instances with modified options.
 -- 't' has to have an instance of the 'SwaggerOptions' class.
 newtype CustomSwagger t a = CustomSwagger {unCustomSwagger :: a}
+  deriving (Generic, Typeable)
 
 class SwaggerOptions xs where
   swaggerOptions :: SchemaOptions
@@ -94,14 +97,7 @@ instance (StringModifier f, SwaggerOptions xs) => SwaggerOptions (FieldLabelModi
 instance (StringModifier f, SwaggerOptions xs) => SwaggerOptions (ConstructorTagModifier f ': xs) where
   swaggerOptions = (swaggerOptions @xs) {constructorTagModifier = getStringModifier @f}
 
-instance
-  ( SwaggerOptions t,
-    Generic a,
-    GToSchema (Rep a),
-    TypeHasSimpleShape a "genericDeclareNamedSchemaUnrestricted"
-  ) =>
-  ToSchema (CustomSwagger t a)
-  where
+instance (SwaggerOptions t, Generic a, Typeable a, GToSchema (Rep a), Typeable (CustomSwagger t a), TypeHasSimpleShape a "genericDeclareNamedSchemaUnrestricted") => ToSchema (CustomSwagger t a) where
   declareNamedSchema _ = genericDeclareNamedSchema (swaggerOptions @t) (Proxy @a)
 
 -- ** Specify __what__ to modify

libs/extended/default.nix

@@ -27,8 +27,8 @@
 , servant
 , servant-client
 , servant-client-core
+, servant-openapi3
 , servant-server
-, servant-swagger
 , temporary
 , text
 , tinylog
@@ -60,8 +60,8 @@ mkDerivation {
     servant
     servant-client
     servant-client-core
+    servant-openapi3
     servant-server
-    servant-swagger
     text
     tinylog
     unliftio

libs/extended/extended.cabal

@@ -98,8 +98,8 @@ library
     , servant
     , servant-client
     , servant-client-core
+    , servant-openapi3
     , servant-server
-    , servant-swagger
     , text
     , tinylog
     , unliftio