-
Notifications
You must be signed in to change notification settings - Fork 0
/
plugins.html
301 lines (285 loc) · 15.1 KB
/
plugins.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
<!DOCTYPE html>
<html lang="en">
<head>
<title>Plugins Reference</title>
<link rel="stylesheet" type="text/css" href="css/jazzy.css" />
<link rel="stylesheet" type="text/css" href="css/highlight.css" />
<meta charset='utf-8'>
<script src="js/jquery.min.js" defer></script>
<script src="js/jazzy.js" defer></script>
</head>
<body>
<a title="Plugins Reference"></a>
<header>
<div class="content-wrapper">
<p><a href="index.html">Moya Docs</a> (82% documented)</p>
</div>
</header>
<div class="content-wrapper">
<p id="breadcrumbs">
<a href="index.html">Moya Reference</a>
<img id="carat" src="img/carat.png" />
Plugins Reference
</p>
</div>
<div class="content-wrapper">
<nav class="sidebar">
<ul class="nav-groups">
<li class="nav-group-name">
<a href="Guides.html">Guides</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="authentication.html">Authentication</a>
</li>
<li class="nav-group-task">
<a href="communityprojects.html">CommunityProjects</a>
</li>
<li class="nav-group-task">
<a href="endpoints.html">Endpoints</a>
</li>
<li class="nav-group-task">
<a href="plugins.html">Plugins</a>
</li>
<li class="nav-group-task">
<a href="providers.html">Providers</a>
</li>
<li class="nav-group-task">
<a href="readme.html">README</a>
</li>
<li class="nav-group-task">
<a href="reactiveswift.html">ReactiveSwift</a>
</li>
<li class="nav-group-task">
<a href="releasing.html">Releasing</a>
</li>
<li class="nav-group-task">
<a href="rxswift.html">RxSwift</a>
</li>
<li class="nav-group-task">
<a href="targets.html">Targets</a>
</li>
<li class="nav-group-task">
<a href="testing.html">Testing</a>
</li>
<li class="nav-group-task">
<a href="threading.html">Threading</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Classes.html">Classes</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Classes/CancellableToken.html">CancellableToken</a>
</li>
<li class="nav-group-task">
<a href="Classes/CredentialsPlugin.html">CredentialsPlugin</a>
</li>
<li class="nav-group-task">
<a href="Classes/Endpoint.html">Endpoint</a>
</li>
<li class="nav-group-task">
<a href="Classes/MoyaProvider.html">MoyaProvider</a>
</li>
<li class="nav-group-task">
<a href="Classes/NetworkActivityPlugin.html">NetworkActivityPlugin</a>
</li>
<li class="nav-group-task">
<a href="Classes/NetworkLoggerPlugin.html">NetworkLoggerPlugin</a>
</li>
<li class="nav-group-task">
<a href="Classes/NetworkLoggerPlugin/Configuration.html">– Configuration</a>
</li>
<li class="nav-group-task">
<a href="Classes/Response.html">Response</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Enums.html">Enumerations</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Enums/AuthorizationType.html">AuthorizationType</a>
</li>
<li class="nav-group-task">
<a href="Enums/EndpointSampleResponse.html">EndpointSampleResponse</a>
</li>
<li class="nav-group-task">
<a href="Enums/MoyaError.html">MoyaError</a>
</li>
<li class="nav-group-task">
<a href="Enums/MultiTarget.html">MultiTarget</a>
</li>
<li class="nav-group-task">
<a href="Enums/NetworkActivityChangeType.html">NetworkActivityChangeType</a>
</li>
<li class="nav-group-task">
<a href="Enums/StubBehavior.html">StubBehavior</a>
</li>
<li class="nav-group-task">
<a href="Enums/Task.html">Task</a>
</li>
<li class="nav-group-task">
<a href="Enums/ValidationType.html">ValidationType</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Extensions.html">Extensions</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Extensions/Method.html">Method</a>
</li>
<li class="nav-group-task">
<a href="Extensions/Request.html">Request</a>
</li>
<li class="nav-group-task">
<a href="Extensions/URL.html">URL</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Functions.html">Functions</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Functions.html#/s:4Moya23convertResponseToResult_7request4data5errors0E0OyAA0C0CAA0A5ErrorOGSo17NSHTTPURLResponseCSg_10Foundation10URLRequestVSgAP4DataVSgs0I0_pSgtF">convertResponseToResult(_:request:data:error:)</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Protocols.html">Protocols</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Protocols/AccessTokenAuthorizable.html">AccessTokenAuthorizable</a>
</li>
<li class="nav-group-task">
<a href="Protocols/Cancellable.html">Cancellable</a>
</li>
<li class="nav-group-task">
<a href="Protocols/MoyaProviderType.html">MoyaProviderType</a>
</li>
<li class="nav-group-task">
<a href="Protocols/PluginType.html">PluginType</a>
</li>
<li class="nav-group-task">
<a href="Protocols/RequestType.html">RequestType</a>
</li>
<li class="nav-group-task">
<a href="Protocols/TargetType.html">TargetType</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Structs.html">Structures</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Structs/AccessTokenPlugin.html">AccessTokenPlugin</a>
</li>
<li class="nav-group-task">
<a href="Structs/MultipartFormData.html">MultipartFormData</a>
</li>
<li class="nav-group-task">
<a href="Structs/MultipartFormData/FormDataProvider.html">– FormDataProvider</a>
</li>
<li class="nav-group-task">
<a href="Structs/ProgressResponse.html">ProgressResponse</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Typealiases.html">Type Aliases</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Typealiases.html#/s:4Moya10Completiona">Completion</a>
</li>
<li class="nav-group-task">
<a href="Typealiases.html#/s:4Moya19DownloadDestinationa">DownloadDestination</a>
</li>
<li class="nav-group-task">
<a href="Typealiases.html#/s:4Moya5Imagea">Image</a>
</li>
<li class="nav-group-task">
<a href="Typealiases.html#/ImageType">ImageType</a>
</li>
<li class="nav-group-task">
<a href="Typealiases.html#/s:4Moya9ImageTypea">ImageType</a>
</li>
<li class="nav-group-task">
<a href="Typealiases.html#/s:4Moya12JSONEncodinga">JSONEncoding</a>
</li>
<li class="nav-group-task">
<a href="Typealiases.html#/s:4Moya6Methoda">Method</a>
</li>
<li class="nav-group-task">
<a href="Typealiases.html#/s:4Moya17ParameterEncodinga">ParameterEncoding</a>
</li>
<li class="nav-group-task">
<a href="Typealiases.html#/s:4Moya13ProgressBlocka">ProgressBlock</a>
</li>
<li class="nav-group-task">
<a href="Typealiases.html#/s:4Moya18RequestInterceptora">RequestInterceptor</a>
</li>
<li class="nav-group-task">
<a href="Typealiases.html#/s:4Moya24RequestMultipartFormDataa">RequestMultipartFormData</a>
</li>
<li class="nav-group-task">
<a href="Typealiases.html#/s:4Moya7Sessiona">Session</a>
</li>
<li class="nav-group-task">
<a href="Typealiases.html#/s:4Moya11URLEncodinga">URLEncoding</a>
</li>
</ul>
</li>
</ul>
</nav>
<article class="main-content">
<section>
<section class="section">
<h1 id='plugins' class='heading'>Plugins</h1>
<p>Moya plugins are used to modify requests and responses or perform side-effects.
A plugin is called:</p>
<ul>
<li>(<code>prepare</code>) after Moya has resolved the <code><a href="Protocols/TargetType.html">TargetType</a></code> to a <code>URLRequest</code>.
This is an opportunity to modify the request before it is sent (e.g. add
headers).</li>
<li>(<code>willSend</code>) before a request is about to be sent. This is an
opportunity to inspect the request and perform any side-effects (e.g. logging).</li>
<li>(<code>didReceive</code>) after a response has been received. This is an
opportunity to inspect the response and perform side-effects.</li>
<li>(<code>process</code>) before <code>completion</code> is called with the <code>Result</code>. This is
an opportunity to make any modifications to the <code>Result</code> of the <code>request</code>.</li>
</ul>
<h2 id='built-in-plugins' class='heading'>Built-in plugins</h2>
<p>Moya ships with some default plugins which can be used for common functions: authentication, network activity indicator management and logging.
You can use a plugin simply declaring it during the initialization of the provider:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">provider</span> <span class="o">=</span> <span class="kt">MoyaProvider</span><span class="o"><</span><span class="kt">GitHub</span><span class="o">></span><span class="p">(</span><span class="nv">plugins</span><span class="p">:</span> <span class="p">[</span><span class="kt">NetworkLoggerPlugin</span><span class="p">()])</span>
</code></pre>
<h3 id='authentication' class='heading'>Authentication</h3>
<h4 id='urlcredential' class='heading'>URLCredential</h4>
<p>The authentication plugin allows a user to assign an optional <code>URLCredential</code> per request. There is no action when a request is received.</p>
<p>The plugin can be found at <a href="../Sources/Moya/Plugins/CredentialsPlugin.swift"><code>Sources/Moya/Plugins/CredentialsPlugin.swift</code></a></p>
<h3 id='access-token' class='heading'>Access Token</h3>
<p>The <code><a href="Structs/AccessTokenPlugin.html">AccessTokenPlugin</a></code> adds the <code>Authorization</code> field in the request’s header if the target requires it.
Before sending the request, the plugin will ask for a token of a specified type using its <code>tokenClosure</code>, and add the appropriate value to headers.</p>
<p>The plugin can be found at <a href="../Sources/Moya/Plugins/AccessTokenPlugin.swift"><code>Sources/Moya/Plugins/AccessTokenPlugin.swift</code></a></p>
<h3 id='network-activity-indicator' class='heading'>Network Activity Indicator</h3>
<p>One very common task with iOS networking is to show a network activity indicator during network requests, and remove it when all requests have finished. The provided plugin adds callbacks which are called when a requests starts and finishes, which can be used to keep track of the number of requests in progress, and show / hide the network activity indicator accordingly.</p>
<p>The plugin can be found at <a href="../Sources/Moya/Plugins/NetworkActivityPlugin.swift"><code>Sources/Moya/Plugins/NetworkActivityPlugin.swift</code></a></p>
<h3 id='logging' class='heading'>Logging</h3>
<p>During development it can be very useful to log network activity to the console. This can be anything from the URL of a request as sent and received, to logging full headers, method, request body on each request and response.</p>
<p>The provided plugin for logging is the most complex of the provided plugins, and can be configured to suit the amount of logging your app (and build type) require. When initializing the plugin, you can choose options for verbosity, whether to log curl commands, and provide functions for outputting data (useful if you are using your own log framework instead of <code>print</code>) and formatting data before printing (by default the response will be converted to a String using <code>String.Encoding.utf8</code> but if you’d like to convert to pretty-printed JSON for your responses you can pass in a formatter function, see the function <code>JSONResponseDataFormatter</code> in <a href="../Examples/_shared/GitHubAPI.swift"><code>Examples/_shared/GitHubAPI.swift</code></a> for an example that does exactly that)</p>
<p>The plugin can be found at <a href="../Sources/Moya/Plugins/NetworkLoggerPlugin.swift"><code>Sources/Moya/Plugins/NetworkLoggerPlugin.swift</code></a></p>
<h2 id='custom-plugins' class='heading'>Custom plugins</h2>
<p>Every time you need to execute some pieces of code before a request is sent and/or immediately after a response, you can create a custom plugin, implementing the <code><a href="Protocols/PluginType.html">PluginType</a></code> protocol.
For examples of creating plugins, see <a href="Examples/CustomPlugin.md"><code>docs/Examples/CustomPlugin.md</code></a> and <a href="Examples/AuthPlugin.md"><code>docs/Examples/AuthPlugin.md</code></a>.</p>
</section>
</section>
<section id="footer">
<p>© 2020 <a class="link" href="https://github.com/Moya/Moya" target="_blank" rel="external">Ash Furrow</a>. All rights reserved. (Last updated: 2020-02-24)</p>
<p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.9.6</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external">Realm</a> project.</p>
</section>
</article>
</div>
</body>
</div>
</html>