From 7c9ef45df10e14e9ae240a27dfc1c2428bcd836d Mon Sep 17 00:00:00 2001 From: Boyd Stephen Smith Jr Date: Sun, 28 Aug 2022 23:20:28 -0500 Subject: [PATCH 1/8] docs(swagger): Remove old swagger Client model Old swagger Client model was unused. --- libs/wire-api/src/Wire/API/Swagger.hs | 1 - libs/wire-api/src/Wire/API/User/Client.hs | 27 ----------------------- 2 files changed, 28 deletions(-) diff --git a/libs/wire-api/src/Wire/API/Swagger.hs b/libs/wire-api/src/Wire/API/Swagger.hs index a83d78587a..a9915a6b35 100644 --- a/libs/wire-api/src/Wire/API/Swagger.hs +++ b/libs/wire-api/src/Wire/API/Swagger.hs @@ -118,7 +118,6 @@ models = User.Client.modelNewClient, User.Client.modelUpdateClient, User.Client.modelDeleteClient, - User.Client.modelClient, User.Client.modelSigkeys, User.Client.modelLocation, -- re-export from types-common User.Client.Prekey.modelPrekey, diff --git a/libs/wire-api/src/Wire/API/User/Client.hs b/libs/wire-api/src/Wire/API/User/Client.hs index 6f38cc75f6..acc0f60c3b 100644 --- a/libs/wire-api/src/Wire/API/User/Client.hs +++ b/libs/wire-api/src/Wire/API/User/Client.hs @@ -72,7 +72,6 @@ module Wire.API.User.Client modelClientCapabilityList, typeClientCapability, modelDeleteClient, - modelClient, modelSigkeys, modelLocation, -- re-export from types-common ) @@ -501,32 +500,6 @@ mlsPublicKeysSchema = (map_ base64Schema) ) -modelClient :: Doc.Model -modelClient = Doc.defineModel "Client" $ do - Doc.description "A registered client." - Doc.property "type" typeClientType $ - Doc.description "The client type." - Doc.property "id" Doc.string' $ - Doc.description "The client ID." - Doc.property "label" Doc.string' $ do - Doc.description "An optional label associated with the client." - Doc.optional - Doc.property "time" Doc.dateTime' $ - Doc.description "The date and time when this client was registered." - Doc.property "class" typeClientClass $ - Doc.description "The device class this client belongs to." - Doc.property "cookie" Doc.string' $ - Doc.description "The cookie label of this client." - Doc.property "address" Doc.string' $ do - Doc.description "IP address from which this client has been registered" - Doc.optional - Doc.property "location" (Doc.ref modelLocation) $ do - Doc.description "Location from which this client has been registered." - Doc.optional - Doc.property "model" Doc.string' $ do - Doc.description "Optional model information of this client" - Doc.optional - -------------------------------------------------------------------------------- -- PubClient From 07477a56968342a3df62aa977c80a87a82877d80 Mon Sep 17 00:00:00 2001 From: Boyd Stephen Smith Jr Date: Sun, 28 Aug 2022 18:30:03 -0500 Subject: [PATCH 2/8] docs(swagger): Add mls_public_keys description --- libs/wire-api/src/Wire/API/User/Client.hs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/libs/wire-api/src/Wire/API/User/Client.hs b/libs/wire-api/src/Wire/API/User/Client.hs index acc0f60c3b..791678641a 100644 --- a/libs/wire-api/src/Wire/API/User/Client.hs +++ b/libs/wire-api/src/Wire/API/User/Client.hs @@ -495,8 +495,9 @@ mlsPublicKeysSchema :: ObjectSchema SwaggerDoc MLSPublicKeys mlsPublicKeysSchema = fmap (fromMaybe mempty) - ( optField + ( optFieldWithDocModifier "mls_public_keys" + (description ?~ "Mapping from signature scheme (tags) to public key data") (map_ base64Schema) ) From 1a8cbfc65a2adbffe27c81e39443e0a294c50a34 Mon Sep 17 00:00:00 2001 From: Boyd Stephen Smith Jr Date: Wed, 31 Aug 2022 10:19:47 -0500 Subject: [PATCH 3/8] docs(swagger): Add base64-specific example string --- libs/types-common/src/Data/Json/Util.hs | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/libs/types-common/src/Data/Json/Util.hs b/libs/types-common/src/Data/Json/Util.hs index ab58254a87..daeed51852 100644 --- a/libs/types-common/src/Data/Json/Util.hs +++ b/libs/types-common/src/Data/Json/Util.hs @@ -49,13 +49,12 @@ module Data.Json.Util where import qualified Cassandra as CQL -import Control.Lens (coerced, (%~), (?~)) +import Control.Lens hiding ((#), (.=)) import Data.Aeson (FromJSON (..), ToJSON (..)) import qualified Data.Aeson as A import qualified Data.Aeson.Types as A import qualified Data.Attoparsec.Text as Atto import qualified Data.Attoparsec.Time as Atto -import Data.Bifunctor import qualified Data.ByteString.Base64 as B64 import qualified Data.ByteString.Base64.URL as B64U import qualified Data.ByteString.Builder as BB @@ -205,8 +204,11 @@ instance ToHttpApiData Base64ByteString where instance S.ToParamSchema Base64ByteString where toParamSchema _ = mempty & S.type_ ?~ S.SwaggerString +-- base64("example") ~> "ZXhhbXBsZQo=" base64SchemaN :: ValueSchema NamedSwaggerDoc ByteString -base64SchemaN = toBase64Text .= parsedText "Base64ByteString" fromBase64Text +base64SchemaN = + (toBase64Text .= parsedText "Base64ByteString" fromBase64Text) + & doc %~ fmap (S.schema . S.example ?~ A.String "ZXhhbXBsZQo=") base64Schema :: ValueSchema SwaggerDoc ByteString base64Schema = unnamed base64SchemaN From f7d3cfc29b120ffdf65bd3de01e6718d7eba17de Mon Sep 17 00:00:00 2001 From: Boyd Stephen Smith Jr Date: Wed, 31 Aug 2022 12:19:50 -0500 Subject: [PATCH 4/8] docs(swagger): Add MLSPublicKeys example value --- libs/wire-api/src/Wire/API/User/Client.hs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/libs/wire-api/src/Wire/API/User/Client.hs b/libs/wire-api/src/Wire/API/User/Client.hs index 791678641a..f9258e3ff5 100644 --- a/libs/wire-api/src/Wire/API/User/Client.hs +++ b/libs/wire-api/src/Wire/API/User/Client.hs @@ -79,7 +79,7 @@ where import qualified Cassandra as Cql import Control.Applicative -import Control.Lens (over, view, (?~), (^.)) +import Control.Lens hiding (element, enum, set, (#), (.=)) import Data.Aeson (FromJSON (..), ToJSON (..)) import qualified Data.Aeson as A import qualified Data.Aeson.Key as Key @@ -96,6 +96,7 @@ import Data.Qualified import Data.Schema import qualified Data.Semigroup as Semigroup import qualified Data.Set as Set +import Data.Swagger hiding (Schema, ToSchema, schema) import qualified Data.Swagger as Swagger import qualified Data.Swagger.Build.Api as Doc import qualified Data.Text.Encoding as Text.E @@ -497,9 +498,14 @@ mlsPublicKeysSchema = (fromMaybe mempty) ( optFieldWithDocModifier "mls_public_keys" - (description ?~ "Mapping from signature scheme (tags) to public key data") + ( (description ?~ "Mapping from signature scheme (tags) to public key data") + . fmap (example ?~ toJSON (Map.fromList $ map (,"base64==" :: Text) keys)) + ) (map_ base64Schema) ) + where + keys :: [SignatureSchemeTag] + keys = [minBound .. maxBound] -------------------------------------------------------------------------------- -- PubClient From 6a7e431ad409d7cab80eeb3177656e480b8f3362 Mon Sep 17 00:00:00 2001 From: Boyd Stephen Smith Jr Date: Wed, 31 Aug 2022 13:24:26 -0500 Subject: [PATCH 5/8] refactor(split): MLSPublicKeys: separate modifiers General type modifiers for MLSPublicKeys (like name, description) are applied in one location, but adapter for use as an optional field named "mls_public_keys" are done separately. Also, generalize a HasDescription instance. --- libs/schema-profunctor/src/Data/Schema.hs | 9 ++++-- libs/wire-api/src/Wire/API/User/Client.hs | 38 +++++++++++++---------- 2 files changed, 27 insertions(+), 20 deletions(-) diff --git a/libs/schema-profunctor/src/Data/Schema.hs b/libs/schema-profunctor/src/Data/Schema.hs index 3ff9e560f3..71c29aaaac 100644 --- a/libs/schema-profunctor/src/Data/Schema.hs +++ b/libs/schema-profunctor/src/Data/Schema.hs @@ -888,8 +888,11 @@ instance S.HasSchema NamedSwaggerDoc S.Schema where instance S.HasSchema d S.Schema => S.HasSchema (SchemaP d v w a b) S.Schema where schema = doc . S.schema -instance S.HasDescription SwaggerDoc (Maybe Text) where - description = declared . S.description - instance S.HasDescription NamedSwaggerDoc (Maybe Text) where description = declared . S.schema . S.description + +instance {-# OVERLAPPABLE #-} S.HasDescription s a => S.HasDescription (WithDeclare s) a where + description = declared . S.description + +instance S.HasExample s a => S.HasExample (WithDeclare s) a where + example = declared . S.example diff --git a/libs/wire-api/src/Wire/API/User/Client.hs b/libs/wire-api/src/Wire/API/User/Client.hs index f9258e3ff5..99acbbe7c1 100644 --- a/libs/wire-api/src/Wire/API/User/Client.hs +++ b/libs/wire-api/src/Wire/API/User/Client.hs @@ -477,6 +477,22 @@ data Client = Client type MLSPublicKeys = Map SignatureSchemeTag ByteString +mlsPublicKeysSchema :: ValueSchema NamedSwaggerDoc MLSPublicKeys +mlsPublicKeysSchema = + mapSchema + & doc + %~ ( (description ?~ "Mapping from signature scheme (tags) to public key data") + . (example ?~ toJSON (Map.fromList $ map (,exampleValue) keys)) + ) + & named "MLSPublicKeys" + where + keys :: [SignatureSchemeTag] + keys = [minBound .. maxBound] + exampleValue = fromMaybe (toJSON ("base64==" :: Text)) (valueSchema ^. doc . example) + valueSchema = base64Schema + mapSchema :: ValueSchema SwaggerDoc MLSPublicKeys + mapSchema = map_ valueSchema + instance ToSchema Client where schema = object "Client" $ @@ -490,22 +506,10 @@ instance ToSchema Client where <*> clientLocation .= maybe_ (optField "location" schema) <*> clientModel .= maybe_ (optField "model" schema) <*> clientCapabilities .= (fromMaybe mempty <$> optField "capabilities" schema) - <*> clientMLSPublicKeys .= mlsPublicKeysSchema + <*> clientMLSPublicKeys .= mlsPublicKeysFieldSchema -mlsPublicKeysSchema :: ObjectSchema SwaggerDoc MLSPublicKeys -mlsPublicKeysSchema = - fmap - (fromMaybe mempty) - ( optFieldWithDocModifier - "mls_public_keys" - ( (description ?~ "Mapping from signature scheme (tags) to public key data") - . fmap (example ?~ toJSON (Map.fromList $ map (,"base64==" :: Text) keys)) - ) - (map_ base64Schema) - ) - where - keys :: [SignatureSchemeTag] - keys = [minBound .. maxBound] +mlsPublicKeysFieldSchema :: ObjectSchema SwaggerDoc MLSPublicKeys +mlsPublicKeysFieldSchema = fromMaybe mempty <$> optField "mls_public_keys" mlsPublicKeysSchema -------------------------------------------------------------------------------- -- PubClient @@ -718,7 +722,7 @@ instance ToSchema NewClient where ) <*> newClientModel .= maybe_ (optField "model" schema) <*> newClientCapabilities .= maybe_ capabilitiesFieldSchema - <*> newClientMLSPublicKeys .= mlsPublicKeysSchema + <*> newClientMLSPublicKeys .= mlsPublicKeysFieldSchema <*> newClientVerificationCode .= maybe_ (optField "verification_code" schema) newClient :: ClientType -> LastPrekey -> NewClient @@ -788,7 +792,7 @@ instance ToSchema UpdateClient where schema ) <*> updateClientCapabilities .= maybe_ capabilitiesFieldSchema - <*> updateClientMLSPublicKeys .= mlsPublicKeysSchema + <*> updateClientMLSPublicKeys .= mlsPublicKeysFieldSchema modelUpdateClient :: Doc.Model modelUpdateClient = Doc.defineModel "UpdateClient" $ do From 3ad2b9320ba69485006e0aaf7c752341c412388a Mon Sep 17 00:00:00 2001 From: Boyd Stephen Smith Jr Date: Sun, 28 Aug 2022 19:54:43 -0500 Subject: [PATCH 6/8] docs(changelog) --- changelog.d/4-docs/FS-672 | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 changelog.d/4-docs/FS-672 diff --git a/changelog.d/4-docs/FS-672 b/changelog.d/4-docs/FS-672 new file mode 100644 index 0000000000..be42870674 --- /dev/null +++ b/changelog.d/4-docs/FS-672 @@ -0,0 +1,2 @@ +Drop Client model (unused) from old swagger. +Add a description and example data for mls_public_keys field in new swagger. From e7e686637f37705c4c3741794233265d2305cf45 Mon Sep 17 00:00:00 2001 From: Boyd Stephen Smith Jr Date: Thu, 1 Sep 2022 05:48:01 -0500 Subject: [PATCH 7/8] refactor: where clause taste Co-authored-by: fisx --- libs/wire-api/src/Wire/API/User/Client.hs | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/libs/wire-api/src/Wire/API/User/Client.hs b/libs/wire-api/src/Wire/API/User/Client.hs index 99acbbe7c1..7efbe1b78f 100644 --- a/libs/wire-api/src/Wire/API/User/Client.hs +++ b/libs/wire-api/src/Wire/API/User/Client.hs @@ -488,10 +488,12 @@ mlsPublicKeysSchema = where keys :: [SignatureSchemeTag] keys = [minBound .. maxBound] - exampleValue = fromMaybe (toJSON ("base64==" :: Text)) (valueSchema ^. doc . example) - valueSchema = base64Schema + + exampleValue :: A.Value + exampleValue = fromMaybe (toJSON ("base64==" :: Text)) (base64Schema ^. doc . example) + mapSchema :: ValueSchema SwaggerDoc MLSPublicKeys - mapSchema = map_ valueSchema + mapSchema = map_ base64Schema instance ToSchema Client where schema = From 461c21a4f38ec5854555def1d06fd222eee03880 Mon Sep 17 00:00:00 2001 From: Boyd Stephen Smith Jr Date: Thu, 1 Sep 2022 05:49:10 -0500 Subject: [PATCH 8/8] refactor: allow overlaps of HasExample like HasDescription Co-authored-by: fisx --- libs/schema-profunctor/src/Data/Schema.hs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libs/schema-profunctor/src/Data/Schema.hs b/libs/schema-profunctor/src/Data/Schema.hs index 71c29aaaac..f2cdd73dcb 100644 --- a/libs/schema-profunctor/src/Data/Schema.hs +++ b/libs/schema-profunctor/src/Data/Schema.hs @@ -894,5 +894,5 @@ instance S.HasDescription NamedSwaggerDoc (Maybe Text) where instance {-# OVERLAPPABLE #-} S.HasDescription s a => S.HasDescription (WithDeclare s) a where description = declared . S.description -instance S.HasExample s a => S.HasExample (WithDeclare s) a where +instance {-# OVERLAPPABLE #-} S.HasExample s a => S.HasExample (WithDeclare s) a where example = declared . S.example