From e44821bce8f1191169449e5a54dff8cc58bfff27 Mon Sep 17 00:00:00 2001 From: jk234ert Date: Fri, 19 Feb 2021 17:40:05 +0800 Subject: [PATCH] feat: refactor the mastodonSDK chore: update API docs --- .../MastodonRegisterViewController.swift | 2 +- .../API/Mastodon+API+Account.swift | 28 +++++++++++++------ .../API/Mastodon+API+Instance.swift | 2 +- .../MastodonSDK/API/Mastodon+API+OAuth.swift | 2 +- .../API/Mastodon+API+Timeline.swift | 26 +++++++++++++++++ .../MastodonSDK/API/Mastodon+API.swift | 15 ++++------ .../Sources/MastodonSDK/Protocol/Query.swift | 23 ++++++++------- 7 files changed, 67 insertions(+), 31 deletions(-) diff --git a/Mastodon/Scene/Authentication/Register/MastodonRegisterViewController.swift b/Mastodon/Scene/Authentication/Register/MastodonRegisterViewController.swift index 0a8e69f5b..db9f30858 100644 --- a/Mastodon/Scene/Authentication/Register/MastodonRegisterViewController.swift +++ b/Mastodon/Scene/Authentication/Register/MastodonRegisterViewController.swift @@ -186,7 +186,7 @@ extension MastodonRegisterViewController { viewModel.isRegistering.value = true let query = Mastodon.API.Account.RegisterQuery( - reason: "", + reason: nil, username: username, email: email, password: password, diff --git a/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+Account.swift b/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+Account.swift index 31e323086..02ea7ff11 100644 --- a/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+Account.swift +++ b/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+Account.swift @@ -22,7 +22,8 @@ extension Mastodon.API.Account { /// Test to make sure that the user token works. /// - /// - Version: 3.0.0 + /// - Since: 0.0.0 + /// - Version: 3.3.0 /// # Last Update /// 2021/2/9 /// # Reference @@ -30,6 +31,7 @@ extension Mastodon.API.Account { /// - Parameters: /// - session: `URLSession` /// - domain: Mastodon instance domain. e.g. "example.com" + /// - authorization: App token /// - Returns: `AnyPublisher` contains `Account` nested in the response public static func verifyCredentials( session: URLSession, @@ -51,7 +53,8 @@ extension Mastodon.API.Account { /// Creates a user and account records. /// - /// - Version: 3.0.0 + /// - Since: 2.7.0 + /// - Version: 3.3.0 /// # Last Update /// 2021/2/9 /// # Reference @@ -59,6 +62,8 @@ extension Mastodon.API.Account { /// - Parameters: /// - session: `URLSession` /// - domain: Mastodon instance domain. e.g. "example.com" + /// - query: `RegisterQuery` with account registration information + /// - authorization: App token /// - Returns: `AnyPublisher` contains `Token` nested in the response public static func register( session: URLSession, @@ -81,7 +86,8 @@ extension Mastodon.API.Account { /// Update the user's display and preferences. /// - /// - Version: 3.0.0 + /// - Since: 1.1.1 + /// - Version: 3.3.0 /// # Last Update /// 2021/2/9 /// # Reference @@ -89,12 +95,13 @@ extension Mastodon.API.Account { /// - Parameters: /// - session: `URLSession` /// - domain: Mastodon instance domain. e.g. "example.com" - /// - query: `CredentialQuery` with update information + /// - query: `CredentialQuery` with update credential information + /// - authorization: `UpdateCredentialQuery` with update information /// - Returns: `AnyPublisher` contains updated `Account` nested in the response public static func updateCredentials( session: URLSession, domain: String, - query: CredentialQuery, + query: UpdateCredentialQuery, authorization: Mastodon.API.OAuth.Authorization ) -> AnyPublisher, Error> { let request = Mastodon.API.patch( @@ -112,7 +119,8 @@ extension Mastodon.API.Account { /// View information about a profile. /// - /// - Version: 3.0.0 + /// - Since: 0.0.0 + /// - Version: 3.3.0 /// # Last Update /// 2021/2/9 /// # Reference @@ -120,12 +128,14 @@ extension Mastodon.API.Account { /// - Parameters: /// - session: `URLSession` /// - domain: Mastodon instance domain. e.g. "example.com" + /// - query: `AccountInfoQuery` with account query information, + /// - authorization: user token /// - Returns: `AnyPublisher` contains `Account` nested in the response public static func accountInfo( session: URLSession, domain: String, query: AccountInfoQuery, - authorization: Mastodon.API.OAuth.Authorization + authorization: Mastodon.API.OAuth.Authorization? ) -> AnyPublisher, Error> { let request = Mastodon.API.get( url: accountsEndpointURL(domain: domain), @@ -162,7 +172,7 @@ extension Mastodon.API.Account { } } - public struct CredentialQuery: Codable, PatchQuery { + public struct UpdateCredentialQuery: Codable, PatchQuery { public var discoverable: Bool? public var bot: Bool? @@ -177,7 +187,7 @@ extension Mastodon.API.Account { enum CodingKeys: String, CodingKey { case discoverable case bot - case displayName + case displayName = "display_name" case note case avatar diff --git a/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+Instance.swift b/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+Instance.swift index bd7a01bcd..e91aaa7b7 100644 --- a/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+Instance.swift +++ b/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+Instance.swift @@ -16,7 +16,7 @@ extension Mastodon.API.Instance { /// Information about the server /// - /// - Since: 1.0.0 + /// - Since: 1.1.0 /// - Version: 3.3.0 /// # Last Update /// 2021/2/5 diff --git a/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+OAuth.swift b/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+OAuth.swift index 1ab74625b..332d78a38 100644 --- a/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+OAuth.swift +++ b/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+OAuth.swift @@ -38,7 +38,7 @@ extension Mastodon.API.OAuth { /// /// This method construct a URL for user authorize /// - /// - Since: 0.1.0 + /// - Since: 0.0.0 /// - Version: 3.3.0 /// # Last Update /// 2021/1/29 diff --git a/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+Timeline.swift b/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+Timeline.swift index 80e30701a..d4ec364bf 100644 --- a/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+Timeline.swift +++ b/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API+Timeline.swift @@ -17,6 +17,19 @@ extension Mastodon.API.Timeline { return Mastodon.API.endpointURL(domain: domain).appendingPathComponent("timelines/home") } + /// View public timeline statuses + /// + /// - Since: 0.0.0 + /// - Version: 3.3.0 + /// # Last Update + /// 2021/2/19 + /// # Reference + /// [Document](https://https://docs.joinmastodon.org/methods/timelines/) + /// - Parameters: + /// - session: `URLSession` + /// - domain: Mastodon instance domain. e.g. "example.com" + /// - query: `PublicTimelineQuery` with query parameters + /// - Returns: `AnyPublisher` contains `Token` nested in the response public static func `public`( session: URLSession, domain: String, @@ -35,6 +48,19 @@ extension Mastodon.API.Timeline { .eraseToAnyPublisher() } + /// View statuses from followed users. + /// + /// - Since: 0.0.0 + /// - Version: 3.3.0 + /// # Last Update + /// 2021/2/19 + /// # Reference + /// [Document](https://https://docs.joinmastodon.org/methods/timelines/) + /// - Parameters: + /// - session: `URLSession` + /// - domain: Mastodon instance domain. e.g. "example.com" + /// - query: `PublicTimelineQuery` with query parameters + /// - Returns: `AnyPublisher` contains `Token` nested in the response public static func home( session: URLSession, domain: String, diff --git a/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API.swift b/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API.swift index aaa38a4db..69a419621 100644 --- a/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API.swift +++ b/MastodonSDK/Sources/MastodonSDK/API/Mastodon+API.swift @@ -96,7 +96,7 @@ extension Mastodon.API { query: GetQuery?, authorization: OAuth.Authorization? ) -> URLRequest { - return buildRequest(url: url, query: query, authorization: authorization) + return buildRequest(url: url, method: .GET, query: query, authorization: authorization) } static func post( @@ -104,7 +104,7 @@ extension Mastodon.API { query: PostQuery?, authorization: OAuth.Authorization? ) -> URLRequest { - return buildRequest(url: url, query: query, authorization: authorization) + return buildRequest(url: url, method: .POST, query: query, authorization: authorization) } static func patch( @@ -112,24 +112,24 @@ extension Mastodon.API { query: PatchQuery?, authorization: OAuth.Authorization? ) -> URLRequest { - return buildRequest(url: url, query: query, authorization: authorization) + return buildRequest(url: url, method: .PATCH, query: query, authorization: authorization) } private static func buildRequest( url: URL, + method: RequestMethod, query: RequestQuery?, authorization: OAuth.Authorization? ) -> URLRequest { var components = URLComponents(string: url.absoluteString)! - if let requestQuery = query as? GetQuery { - components.queryItems = requestQuery.queryItems - } + components.queryItems = query?.queryItems let requestURL = components.url! var request = URLRequest( url: requestURL, cachePolicy: .reloadIgnoringLocalAndRemoteCacheData, timeoutInterval: Mastodon.API.timeoutInterval ) + request.httpMethod = method.rawValue request.setValue("application/json; charset=utf-8", forHTTPHeaderField: "Content-Type") request.httpBody = query?.body if let authorization = authorization { @@ -138,10 +138,7 @@ extension Mastodon.API { forHTTPHeaderField: Mastodon.API.OAuth.authorizationField ) } - - request.httpMethod = query?.method.rawValue ?? RequestMethod.GET.rawValue return request - } static func decode(type: T.Type, from data: Data, response: URLResponse) throws -> T where T : Decodable { diff --git a/MastodonSDK/Sources/MastodonSDK/Protocol/Query.swift b/MastodonSDK/Sources/MastodonSDK/Protocol/Query.swift index 5cf88809c..7a6608d66 100644 --- a/MastodonSDK/Sources/MastodonSDK/Protocol/Query.swift +++ b/MastodonSDK/Sources/MastodonSDK/Protocol/Query.swift @@ -12,33 +12,36 @@ enum RequestMethod: String { } protocol RequestQuery { + // All kinds of queries could have queryItems and body + var queryItems: [URLQueryItem]? { get } var body: Data? { get } - var method: RequestMethod { get } } +// An `Encodable` query provides its body by encoding itself +// A `Get` query only contains queryItems, it should not be `Encodable` extension RequestQuery where Self: Encodable { var body: Data? { return try? Mastodon.API.encoder.encode(self) } } -protocol GetQuery: RequestQuery { - var queryItems: [URLQueryItem]? { get } -} +protocol GetQuery: RequestQuery { } extension GetQuery { - var method: RequestMethod { return .GET } - var body: Data? { return nil } + // By default a `GetQuery` does not has data body + var body: Data? { nil } } -protocol PostQuery: RequestQuery { } +protocol PostQuery: RequestQuery & Encodable { } extension PostQuery { - var method: RequestMethod { return .POST } + // By default a `GetQuery` does not has query items + var queryItems: [URLQueryItem]? { nil } } -protocol PatchQuery: RequestQuery { } +protocol PatchQuery: RequestQuery & Encodable { } extension PatchQuery { - var method: RequestMethod { return .PATCH } + // By default a `GetQuery` does not has query items + var queryItems: [URLQueryItem]? { nil } }