Make a start on using OpenAPI3

OpenAPI3 will allow us to properly pass the Bearer Auth to the servant
swagger UI.

gargantext.cabal

@@ -467,6 +467,8 @@ library
       Gargantext.Database.Schema.NodeNode
       Gargantext.Database.Schema.Prelude
       Gargantext.Database.Types
+      Gargantext.Orphans
+      Gargantext.Orphans.OpenAPI
       Gargantext.Utils.Aeson
       Gargantext.Utils.Servant
       Gargantext.Utils.UTCTime
@@ -562,6 +564,7 @@ library
     , opaleye ^>= 0.9.6.1
     , opaleye-textsearch >= 0.2.0.0
     , openalex
+    , openapi3 >= 3.2.3
     , parallel ^>= 3.2.2.0
     , parsec ^>= 3.1.16.1
     , patches-class ^>= 0.1.0.1
@@ -588,6 +591,7 @@ library
     , servant-client-core >= 0.20 && < 0.21
     , servant-ekg ^>= 0.3.1
     , servant-routes < 0.2
+    , servant-openapi3 >= 2.0.1.6
     , servant-server >= 0.18.3 && < 0.21
     , servant-swagger ^>= 1.2
     , servant-swagger-ui ^>= 0.3.5.3.5.0

src/Gargantext/API/Auth/PolicyCheck.hs

@@ -64,6 +64,7 @@ import Servant (HasServer(..), ServerT)
 import Servant.Server.Internal.Delayed (addParameterCheck)
 import Servant.Server.Internal.DelayedIO (DelayedIO(..))
 import Servant.Swagger qualified as Swagger
+import Servant.OpenApi qualified as OpenAPI
 
 -------------------------------------------------------------------------------
 -- Types
@@ -299,6 +300,9 @@ instance AddSetCookies ('S n) old new => AddSetCookies ('S n) (AccessPolicyManag
 instance Swagger.HasSwagger sub => Swagger.HasSwagger (PolicyChecked sub) where
     toSwagger _ = Swagger.toSwagger (Proxy :: Proxy sub)
 
+instance OpenAPI.HasOpenApi sub => OpenAPI.HasOpenApi (PolicyChecked sub) where
+    toOpenApi _ = OpenAPI.toOpenApi (Proxy :: Proxy sub)
+
 instance HasEndpoint sub => HasEndpoint (PolicyChecked sub) where
   getEndpoint _ = getEndpoint (Proxy :: Proxy sub)
   enumerateEndpoints _ = enumerateEndpoints (Proxy :: Proxy sub)

src/Gargantext/API/Server/Named.hs

@@ -20,7 +20,7 @@ import Gargantext.API.GraphQL as GraphQL
 import Gargantext.API.Prelude (GargM)
 import Gargantext.API.Routes.Named
 import Gargantext.API.Server.Named.Public (serverPublicGargAPI)
-import Gargantext.API.Swagger (swaggerDoc)
+import Gargantext.API.Swagger (openApiDoc)
 import Gargantext.API.ThrowAll (serverPrivateGargAPI)
 import Gargantext.Core.Notifications.Dispatcher.WebSocket qualified as Dispatcher
 import Gargantext.Core.Config (gc_frontend_config, hasConfig)
@@ -50,7 +50,7 @@ serverGargAPI env
 server :: Env -> API AsServer
 server env =
   API $ \errScheme -> NamedAPI
-     { swaggerAPI = swaggerSchemaUIServer swaggerDoc
+     { swaggerAPI = swaggerSchemaUIServer openApiDoc
      , backendAPI = hoistServerWithContext
                       (Proxy :: Proxy (NamedRoutes BackEndAPI))
                       (Proxy :: Proxy AuthContext)

src/Gargantext/API/Swagger.hs

@@ -12,23 +12,37 @@ Portability : POSIX
 -}
 
 ---------------------------------------------------------------------
-module Gargantext.API.Swagger where
+module Gargantext.API.Swagger (
+    backendApiProxy
+  , openApiDoc
+  ) where
+
 ---------------------------------------------------------------------
 import Control.Lens ((?~))
+import Data.OpenApi (OpenApi)
 import Data.Swagger
 import Data.Version (showVersion)
 import Gargantext.API.Routes.Named qualified as Named
+import Gargantext.Orphans () -- instance HasOpenApi
+import Gargantext.Prelude
 import Gargantext.Prelude
-import Paths_gargantext qualified as PG -- cabal magic build module
+import qualified Paths_gargantext as PG -- cabal magic build module
 import Servant
-import Servant.Swagger (toSwagger, subOperations)
+import Servant.OpenApi (toOpenApi)
+import Servant.Swagger
 
 backendApiProxy :: Proxy (ToServantApi Named.BackEndAPI)
 backendApiProxy = Proxy
 
+-- | OpenAPI Specification. It supports programmatically adding the `Bearer` to the `Authorization`
+-- header, which makes the Swagger UI actually useable, unlike the 'swaggerDoc' counterpart which
+-- is stuck on version 2.x of the OpenAPI spec.
+openApiDoc :: OpenApi
+openApiDoc = toOpenApi backendApiProxy
+
 -- | Swagger Specifications
-swaggerDoc :: Swagger
-swaggerDoc = toSwagger backendApiProxy
+_swaggerDoc :: Swagger
+_swaggerDoc = toSwagger backendApiProxy
   & info.title       .~ "GarganText"
   & info.version     .~ (cs $ showVersion PG.version)
   -- & info.base_url     ?~ (URL "http://gargantext.org/")

src/Gargantext/Orphans.hs

+module Gargantext.Orphans (
+  module Gargantext.Orphans.OpenAPI
+  ) where
+
+import Gargantext.Orphans.OpenAPI