WPB-5098 Backend-to-backend OpenApi Docs

changelog.d/4-docs/WPB-5098

@@ -0,0 +1 @@
+Backend-to-backend OpenApi Docs added

charts/nginz/values.yaml

@@ -162,6 +162,10 @@ nginx_conf:
       disable_zauth: true
       envs:
       - staging
+    - path: /api-federation/swagger-ui
+      disable_zauth: true
+      envs:
+      - staging
     - path: /self$ # Matches exactly /self
       oauth_scope: self
       envs:

libs/types-common/src/Data/Json/Util.hs

@@ -196,7 +196,7 @@ toJSONFieldName = A.defaultOptions {A.fieldLabelModifier = A.camelTo2 '_'}
 -- Some related discussion: <https://github.com/bos/aeson/issues/126>.
 newtype Base64ByteString = Base64ByteString {fromBase64ByteString :: ByteString}
   deriving stock (Eq, Ord, Show)
-  deriving (FromJSON, ToJSON) via Schema Base64ByteString
+  deriving (FromJSON, ToJSON, S.ToSchema) via Schema Base64ByteString
   deriving newtype (Arbitrary, IsString)
 
 instance ToSchema Base64ByteString where

libs/wai-utilities/src/Network/Wai/Utilities/JSONResponse.hs

@@ -24,6 +24,7 @@ where
 
 import Data.Aeson (FromJSON (..), ToJSON (..))
 import Data.Aeson qualified as A
+import Data.OpenApi qualified as S
 import Data.Schema
 import Imports
 import Network.HTTP.Types.Status
@@ -43,7 +44,7 @@ data JSONResponse = JSONResponse
     value :: A.Value
   }
   deriving (Eq, Ord, Show)
-  deriving (FromJSON, ToJSON) via Schema JSONResponse
+  deriving (FromJSON, ToJSON, S.ToSchema) via Schema JSONResponse
 
 instance ToSchema JSONResponse where
   schema =

libs/wire-api-federation/default.nix

@@ -33,6 +33,7 @@
 , servant
 , servant-client
 , servant-client-core
+, servant-openapi3
 , servant-server
 , singletons
 , singletons-th
@@ -74,6 +75,7 @@ mkDerivation {
     servant
     servant-client
     servant-client-core
+    servant-openapi3
     servant-server
     singletons-th
     text

libs/wire-api-federation/src/Wire/API/Federation/API/Brig.hs

@@ -25,8 +25,11 @@ import Data.Aeson
 import Data.Domain (Domain)
 import Data.Handle (Handle)
 import Data.Id
+import Data.OpenApi (OpenApi, ToSchema)
+import Data.Proxy (Proxy (Proxy))
 import Imports
 import Servant.API
+import Servant.OpenApi (HasOpenApi (toOpenApi))
 import Test.QuickCheck (Arbitrary)
 import Wire.API.Federation.API.Brig.Notifications as Notifications
 import Wire.API.Federation.Endpoint
@@ -49,6 +52,8 @@ instance ToJSON SearchRequest
 
 instance FromJSON SearchRequest
 
+instance ToSchema SearchRequest
+
 data SearchResponse = SearchResponse
   { contacts :: [Contact],
     searchPolicy :: FederatedUserSearchPolicy
@@ -59,6 +64,8 @@ instance ToJSON SearchResponse
 
 instance FromJSON SearchResponse
 
+instance ToSchema SearchResponse
+
 -- | For conventions see /docs/developer/federation-api-conventions.md
 type BrigApi =
   FedEndpoint "api-version" () VersionInfo
@@ -85,6 +92,8 @@ newtype DomainSet = DomainSet
   deriving stock (Eq, Show, Generic)
   deriving (ToJSON, FromJSON) via (CustomEncoded DomainSet)
 
+instance ToSchema DomainSet
+
 newtype NonConnectedBackends = NonConnectedBackends
   -- TODO:
   -- The encoding rules that were in place would make this "connectedBackends" over the wire.
@@ -94,19 +103,25 @@ newtype NonConnectedBackends = NonConnectedBackends
   deriving stock (Eq, Show, Generic)
   deriving (ToJSON, FromJSON) via (CustomEncoded NonConnectedBackends)
 
+instance ToSchema NonConnectedBackends
+
 newtype GetUserClients = GetUserClients
   { users :: [UserId]
   }
   deriving stock (Eq, Show, Generic)
   deriving (ToJSON, FromJSON) via (CustomEncoded GetUserClients)
 
+instance ToSchema GetUserClients
+
 data MLSClientsRequest = MLSClientsRequest
   { userId :: UserId, -- implicitly qualified by the local domain
     cipherSuite :: CipherSuite
   }
   deriving stock (Eq, Show, Generic)
   deriving (ToJSON, FromJSON) via (CustomEncoded MLSClientsRequest)
 
+instance ToSchema MLSClientsRequest
+
 -- NOTE: ConversationId for remote connections
 --
 -- The plan is to model the connect/one2one conversationId as deterministically derived from
@@ -134,20 +149,26 @@ data NewConnectionRequest = NewConnectionRequest
   deriving (Arbitrary) via (GenericUniform NewConnectionRequest)
   deriving (FromJSON, ToJSON) via (CustomEncoded NewConnectionRequest)
 
+instance ToSchema NewConnectionRequest
+
 data RemoteConnectionAction
   = RemoteConnect
   | RemoteRescind
   deriving stock (Eq, Show, Generic)
   deriving (Arbitrary) via (GenericUniform RemoteConnectionAction)
   deriving (FromJSON, ToJSON) via (CustomEncoded RemoteConnectionAction)
 
+instance ToSchema RemoteConnectionAction
+
 data NewConnectionResponse
   = NewConnectionResponseUserNotActivated
   | NewConnectionResponseOk (Maybe RemoteConnectionAction)
   deriving stock (Eq, Show, Generic)
   deriving (Arbitrary) via (GenericUniform NewConnectionResponse)
   deriving (FromJSON, ToJSON) via (CustomEncoded NewConnectionResponse)
 
+instance ToSchema NewConnectionResponse
+
 data ClaimKeyPackageRequest = ClaimKeyPackageRequest
   { -- | The user making the request, implictly qualified by the origin domain.
     claimant :: UserId,
@@ -160,3 +181,8 @@ data ClaimKeyPackageRequest = ClaimKeyPackageRequest
   deriving stock (Eq, Show, Generic)
   deriving (Arbitrary) via (GenericUniform ClaimKeyPackageRequest)
   deriving (FromJSON, ToJSON) via (CustomEncoded ClaimKeyPackageRequest)
+
+instance ToSchema ClaimKeyPackageRequest
+
+swaggerDoc :: OpenApi
+swaggerDoc = toOpenApi (Proxy @BrigApi)

libs/wire-api-federation/src/Wire/API/Federation/API/Brig/Notifications.hs

@@ -19,6 +19,7 @@ module Wire.API.Federation.API.Brig.Notifications where
 
 import Data.Aeson
 import Data.Id
+import Data.OpenApi (ToSchema)
 import Data.Range
 import Imports
 import Wire.API.Federation.Component
@@ -50,6 +51,8 @@ instance HasNotificationEndpoint 'OnUserDeletedConnectionsTag where
     NotificationAPI 'OnUserDeletedConnectionsTag 'Brig =
       NotificationFedEndpoint 'OnUserDeletedConnectionsTag
 
+instance ToSchema UserDeletedConnectionsNotification
+
 -- | All the notification endpoints return an 'EmptyResponse'.
 type BrigNotificationAPI =
   -- FUTUREWORK: Use NotificationAPI 'OnUserDeletedConnectionsTag 'Brig instead

libs/wire-api-federation/src/Wire/API/Federation/API/Cargohold.hs

@@ -19,18 +19,21 @@ module Wire.API.Federation.API.Cargohold where
 
 import Data.Aeson (FromJSON (..), ToJSON (..))
 import Data.Id
+import Data.OpenApi
+import Data.Proxy
 import Imports
 import Servant.API
+import Servant.OpenApi (HasOpenApi (toOpenApi))
 import Wire.API.Asset
 import Wire.API.Federation.Endpoint
 import Wire.API.Routes.AssetBody
 import Wire.API.Util.Aeson
 import Wire.Arbitrary (Arbitrary, GenericUniform (..))
 
 data GetAsset = GetAsset
-  { -- | User requesting the asset. Implictly qualified with the source domain.
+  { -- | User requesting the asset. Implicitly qualified with the source domain.
     user :: UserId,
-    -- | Asset key for the asset to download. Implictly qualified with the
+    -- | Asset key for the asset to download. Implicitly qualified with the
     -- target domain.
     key :: AssetKey,
     -- | Optional asset token.
@@ -40,12 +43,19 @@ data GetAsset = GetAsset
   deriving (Arbitrary) via (GenericUniform GetAsset)
   deriving (ToJSON, FromJSON) via (CustomEncoded GetAsset)
 
+instance ToSchema GetAsset
+
 data GetAssetResponse = GetAssetResponse
   {available :: Bool}
   deriving stock (Eq, Show, Generic)
   deriving (Arbitrary) via (GenericUniform GetAssetResponse)
   deriving (ToJSON, FromJSON) via (CustomEncoded GetAssetResponse)
 
+instance ToSchema GetAssetResponse
+
 type CargoholdApi =
   FedEndpoint "get-asset" GetAsset GetAssetResponse
     :<|> StreamingFedEndpoint "stream-asset" GetAsset AssetSource
+
+swaggerDoc :: OpenApi
+swaggerDoc = toOpenApi (Proxy @CargoholdApi)

libs/wire-api-federation/src/Wire/API/Federation/API/Common.hs

@@ -18,6 +18,7 @@
 module Wire.API.Federation.API.Common where
 
 import Data.Aeson
+import Data.OpenApi (ToSchema)
 import Imports
 import Test.QuickCheck
 import Wire.Arbitrary
@@ -29,6 +30,8 @@ data EmptyResponse = EmptyResponse
   deriving stock (Eq, Show, Generic)
   deriving (Arbitrary) via (GenericUniform EmptyResponse)
 
+instance ToSchema EmptyResponse
+
 instance FromJSON EmptyResponse where
   parseJSON = withObject "EmptyResponse" . const $ pure EmptyResponse