Aller au contenu
Modifié par Administrateur local le 2024/12/18 11:00
Afficher les derniers auteurs
1
2 Il est possible de paramétrer Swagger via le fichier de configuration Spring "///WEB-INF/beans.xml//" en déclarant :
3 (% style="color: rgb(0,0,255);" %)
4 * (% style="color: rgb(0,0,0);" %)un bean faisant référence à la classe(%%) o(% style="color: rgb(0,0,255);" %)rg.apache.cxf.jaxrs.swagger.Swagger2Feature
5 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)Exemple :(%%)
6 (%%)(%%)
7
8
9 {{code language="none"}}
10 <bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature" lazy-init="true">
11 <property name="basePath" value="/jaxrs/ws"/>
12 <property name="resourcePackage" value="hardis.jaxrs"/>
13 <property name="contact" value="hotline.adelia@hardis.fr" />
14 <property name="title" value="REST Services List" />
15 <property name="description" value="REST services documentation" />
16 <property name="version" value="2.1" />
17 <property name="termsOfServiceUrl" value="http://www.hardis-group.com" />
18 </bean>
19 {{/code}}
20
21 (% style="color: rgb(0,0,255);" %)
22 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)Le bean //Swagger2Feature// doit être référencé au niveau du point d'accès (jaxrs:server) pour activer la production du document //swagger.json// (utilisé par la suite par //Swagger-ui// pour afficher les informations/documentation de vos APis).(%%)(%%)
23 (%%)
24
25
26 {{code language="xml" language="xml"}}
27 <jaxrs:server id="rest" address="/" transportId="http://cxf.apache.org/transports/http">
28 <jaxrs:features>
29 <ref bean="swagger2Feature" />
30 </jaxrs:features>
31 </jaxrs:server>
32 {{/code}}
33
34
35
36 (% style="color: rgb(0,0,255);" %)
37 Détail des propriétés de la feature Swagger2Feature
38 (%%)
39 |=(% colspan="1" rowspan="1" %)(((
40 Name
41 )))|=(% colspan="1" rowspan="1" %)(((
42 Description
43 )))|=(% colspan="1" rowspan="1" %)(((
44 Default
45 )))
46 |(% colspan="1" rowspan="1" %)(((
47 basePath
48 )))|(% colspan="1" rowspan="1" %)(((
49 the context root path+
50 )))|(% colspan="1" rowspan="1" %)(((
51 null
52 )))
53 |(% colspan="1" rowspan="1" %)(((
54 contact
55 )))|(% colspan="1" rowspan="1" %)(((
56 the contact information+
57 )))|(% colspan="1" rowspan="1" %)(((
58 "users@[[cxf.apache.org>>url:http://cxf.apache.org]]"
59 )))
60 |(% colspan="1" rowspan="1" %)(((
61 description
62 )))|(% colspan="1" rowspan="1" %)(((
63 the description+
64 )))|(% colspan="1" rowspan="1" %)(((
65 "The Application"
66 )))
67 |(% colspan="1" rowspan="1" %)(((
68 filterClass
69 )))|(% colspan="1" rowspan="1" %)(((
70 a security filter+
71 )))|(% colspan="1" rowspan="1" %)(((
72 null
73 )))
74 |(% colspan="1" rowspan="1" %)(((
75 host
76 )))|(% colspan="1" rowspan="1" %)(((
77 the host and port+
78 )))|(% colspan="1" rowspan="1" %)(((
79 null
80 )))
81 |(% colspan="1" rowspan="1" %)(((
82 ignoreRoutes
83 )))|(% colspan="1" rowspan="1" %)(((
84 excludes specific paths when scanning all resources (see scanAllResources)++
85 )))|(% colspan="1" rowspan="1" %)(((
86 null
87 )))
88 |(% colspan="1" rowspan="1" %)(((
89 license
90 )))|(% colspan="1" rowspan="1" %)(((
91 the license+
92 )))|(% colspan="1" rowspan="1" %)(((
93 "Apache 2.0 License"
94 )))
95 |(% colspan="1" rowspan="1" %)(((
96 licenceUrl
97 )))|(% colspan="1" rowspan="1" %)(((
98 the license URL+
99 )))|(% colspan="1" rowspan="1" %)(((
100 "[[http://www.apache.org/licenses/LICENSE-2.0.html>>url:http://www.apache.org/licenses/LICENSE-2.0.html]]"
101 )))
102 |(% colspan="1" rowspan="1" %)(((
103 prettyPrint
104 )))|(% colspan="1" rowspan="1" %)(((
105 when generating swagger.json, pretty-print the json document+
106 )))|(% colspan="1" rowspan="1" %)(((
107 false
108 )))
109 |(% colspan="1" rowspan="1" %)(((
110 resourcePackage
111 )))|(% colspan="1" rowspan="1" %)(((
112 a list of comma separated package names where resources must be scanned+
113 )))|(% colspan="1" rowspan="1" %)(((
114 a list of service classes configured at the endpoint
115 )))
116 |(% colspan="1" rowspan="1" %)(((
117 runAsFilter
118 )))|(% colspan="1" rowspan="1" %)(((
119 runs the feature as a filter
120 )))|(% colspan="1" rowspan="1" %)(((
121 false
122 )))
123 |(% colspan="1" rowspan="1" %)(((
124 scan
125 )))|(% colspan="1" rowspan="1" %)(((
126 generates the swagger documentation+
127 )))|(% colspan="1" rowspan="1" %)(((
128 true
129 )))
130 |(% colspan="1" rowspan="1" %)(((
131 scanAllResources
132 )))|(% colspan="1" rowspan="1" %)(((
133 scans all resources including non-annotated JAX-RS resources++
134 )))|(% colspan="1" rowspan="1" %)(((
135 false
136 )))
137 |(% colspan="1" rowspan="1" %)(((
138 schemes
139 )))|(% colspan="1" rowspan="1" %)(((
140 the protocol schemes+
141 )))|(% colspan="1" rowspan="1" %)(((
142 null
143 )))
144 |(% colspan="1" rowspan="1" %)(((
145 termsOfServiceUrl
146 )))|(% colspan="1" rowspan="1" %)(((
147 the terms of service URL+
148 )))|(% colspan="1" rowspan="1" %)(((
149 null
150 )))
151 |(% colspan="1" rowspan="1" %)(((
152 title
153 )))|(% colspan="1" rowspan="1" %)(((
154 the title+
155 )))|(% colspan="1" rowspan="1" %)(((
156 "Sample REST Application"
157 )))
158 |(% colspan="1" rowspan="1" %)(((
159 version
160 )))|(% colspan="1" rowspan="1" %)(((
161 the version+
162 )))|(% colspan="1" rowspan="1" %)(((
163 "1.0.0"
164 )))
165
166
167 (% style="color: rgb(0,0,255);" %)Remarques :
168 (%%)
169 (% style="color: rgb(0,0,255);" %)
170 * (% style="color: rgb(0,0,255);" %)La propriété //resourcePackage// permet de filtrer les ressources (services) scannées et par extension les ressources (services) ajoutées au swagger.json.(%%)
171 (% style="color: rgb(0,0,255);" %)
172 * Les propriétés //scanAllResources//(% style="color: rgb(0,0,255);" %) et //ignoreRoutes// fonctionnent de pair. Si //scanAllResources// a la valeur //true//, il est alors possible d'exclure les ressources (services) des chemins (paths) précisés.(%%)
173 (% style="color: rgb(0,0,255);" %)
174 * (% style="color: rgb(0,0,255);" %)La propriété basePath n'est plus utile car calculée automatiquement.
175 (%%)
176
177 (% style="color: rgb(0,0,255);" %)
178 (%%)(% style="color: rgb(0,0,0);" %)La déclaration d'un bean faisant référence(%%)(% style="color: rgb(0,0,0);" %) à la classe(%%) (% style="color: rgb(0,0,255);" %)//com.hardis.adelia.webservice.SwaggJaxbInit// (% style="color: rgb(0,0,0);" %)permet de modifier les propriétés utile à la sérialisation/désérialisation utile à la production du document swagger.json (s'appuie sur fasterXML/Jackson).
179
180 Exemple :(%%)
181 (%%)
182
183
184 {{code language="none"}}
185 <bean id="SwaggJaxbInit" class="com.hardis.adelia.webservice.SwaggJaxbInit" init-method="init" >
186 <property name="jaxbMapper" value="true"/>
187 <property name="serializeWRAP_ROOT_VALUE" value="false"/>
188 <property name="serializeWRITE_DATES_AS_TIMESTAMPS" value="true"/>
189 <property name="serializeWRITE_DATE_KEYS_AS_TIMESTAMPS" value="false"/>
190 <property name="serializeWRITE_CHAR_ARRAYS_AS_JSON_ARRAYS" value="false"/>
191 <property name="serializeWRITE_EMPTY_JSON_ARRAYS" value="true"/>
192 <property name="serializeWRITE_SINGLE_ELEM_ARRAYS_UNWRAPPED" value="false"/>
193 <property name="deserializeUSE_JAVA_ARRAY_FOR_JSON_ARRAY" value="false"/>
194 <property name="deserializeACCEPT_SINGLE_VALUE_AS_ARRAY" value="false"/>
195 <property name="deserializeUNWRAP_ROOT_VALUE" value="false"/>
196 <property name="deserializeUNWRAP_SINGLE_VALUE_ARRAYS" value="false"/>
197 <property name="deserializeFAIL_ON_IGNORED_PROPERTIES" value="false"/>
198 <property name="deserializeFAIL_ON_UNKNOWN_PROPERTIES" value="true"/>
199 </bean>
200 {{/code}}
201
202 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)Les détails sur les propriétés se trouvent (%%):
203 [[https://github.com/FasterXML/jackson-databind/wiki/Serialization-features>>url:https://github.com/FasterXML/jackson-databind/wiki/Serialization-features]]
204 [[https://github.com/FasterXML/jackson-databind/wiki/Deserialization-Feature>>url:https://github.com/FasterXML/jackson-databind/wiki/Deserialization-Features]](%%)
205 (((
206 = ((% style="color: rgb(255,0,0);" %)V13 PTF9(%%)) =
207 )))
208 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V13 PTF09 intègre les librairies : (%%)(%%)
209 (% style="color: rgb(0,0,0);" %)
210 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.1.6(%%)(%%)
211 (% style="color: rgb(0,0,0);" %)
212 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 1.5.9(%%)(%%)
213 (% style="color: rgb(0,0,0);" %)
214 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.ui 2.(%%)(%%)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)1.4
215 (%%)(%%)
216
217 (((
218 = ((% style="color: rgb(255,0,0);" %)V14 PTF00(%%)) =
219 )))
220 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF00 intègre les librairies : (%%)(%%)
221 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.1.17(%%)(%%)
222 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 1.5.18(%%)(%%)
223 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.ui 3.(%%)(%%)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)13.0(%%)(%%)
224
225 (% style="color: rgb(0,0,0);" %)
226 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
227 Par défaut tous les éléments de swagger-ui sont désormais intégrés dans le .jar //swagger-ui-3.13.0.jar//.
228 La présence dans le bean //Swagger2Feature// (Cf. //beans.xml//) (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)de la propriété (% style="color: rgb(0,0,0);" %)//supportSwaggerUi//(%%)// //avec la valeur fixée à //true// permet de rendre opérationnel //Swagger-ui// sans avoir à décompacter l'archive/jar dans le dossier de l'application web.(%%)(%%)
229
230 L'accès à //Swagger-ui// pour les différents points d'accès (//jaxrs:server//) est disponible via l'URL : http(s):////host//://port/ContextRoot/CXFServletMapping///**services**
231
232 Exemple :
233
234 [[image:image2019-6-4_10-58-13.png]]
235
236
237 Il est possible de paramétrer la page de //Swagger-ui// atteinte par le lien présenté ci-dessus en ajoutant des paramètres à l'url (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)http(s):////host//://port/////ContextRoot/////CXFServletMapping///(%%)(%%)**api-docs**.
238 Par défaut le lien proposé ajoute le paramètre //url//// //pour localiser le fichier swagger.json en entrée. **(?url~=jaxrs/ws/swagger.json)**. D'autres paramètres peuvent être ajoutés permettant par exemple de trier les méthodes ou les tags.
239 Tous les paramètres sont listés dans la page suivante : [[https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md>>url:https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md]]
240 Certaines options de configuration ne peuvent pas être fixées à l'aide de paramètres ; il faut alors modifier le fichier //index.html// inclus dans l'archive swagger-ui-3.x.y.jar.
241
242 La modification du fichier //index.html// permet également d'avoir recours à l'utilisation des objets //requestInterceptor// et //responseInterceptor// lors de la création de l'objet //SwaggerUIBundle//. Ces //"interceptor//" permettent respectivement de modifier la requête adressée au serveur et de modifier la réponse retournée par le serveur avant son affichage.
243 Le (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)//requestInterceptor//(%%)(%%) peut par exemple être utilisé pour ajouter un header HTTP à la requête (exemple : récupérer un jeton JWT passé dans URL pour l'injecter dans le header //Authorization//).
244 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)Le (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)//responseInterceptor//(%%)(%%) peut par exemple modifier le swagger.json retourné afin d'effectuer un filtrage de ressources.(%%)(%%)
245
246 Exemple (//index.html//; ajout dans le header //Authorization// du jeton passé dans l'URL via un paramètre nommé //apiKey//:
247 (%%)(%%)
248
249
250 {{code language="js" title="index.html" language="js"}}
251 <script>
252 function getUrlParameter(name) {
253 name = name.replace(/[\[]/, '\\[').replace(/[\]]/, '\\]');
254 var regex = new RegExp('[\\?&]' + name + '=([^&#]*)');
255 var results = regex.exec(location.search);
256 return results === null ? '' : decodeURIComponent(results[1].replace(/\+/g, ' '));
257 };
258
259 var apiKey = getUrlParameter('apiKey');
260
261 window.onload = function() {
262 // Begin Swagger UI call region
263 const ui = SwaggerUIBundle({
264 url: "/jaxrs/ws/swagger.json",
265 dom_id: '#swagger-ui',
266 deepLinking: true,
267 validatorUrl:null,
268 presets: [
269 SwaggerUIBundle.presets.apis,
270 SwaggerUIStandalonePreset
271 ],
272 plugins: [
273 SwaggerUIBundle.plugins.DownloadUrl
274 ],
275 layout: "StandaloneLayout",
276
277 requestInterceptor: function(request) {
278 request.headers.Authorization = "JWT " + apiKey;
279 return request;
280 }
281 })
282 {{/code}}
283
284
285
286 (% style="color: rgb(0,0,0);" %)
287 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
288 En cliquant sur le lien proposé un peu plus haut (http://localhost:8080/jaxrs/ws/api-docs?url~=/jaxrs/ws/swagger.json), la page suivante (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)s'affiche (%%)(%%):
289
290 [[image:image2019-6-4_11-10-0.png]]
291
292
293 L'exemple de modification du fichier //index.html// vu ci-dessus propose une solution pour automatiser le passage d'un jeton JWT au header //Authorization// à la requête.
294 La gestion du passage du jeton ou des informations d'une authentification de type HTTP Basic peut également se faire via l'interface de Swagger-ui.
295 L'interface de Swagger-ui s'adapte au contenu retourné par le serveur dans le swagger.json ; si ce dernier contient des informations de type(%%)(%%)//SwaggerSecurityDefinitions// alors l'interface offre un bouton [[[Authorize>>doc:ADELIAWIKI.111149831.WebHome]]] permettant de saisir les informations d'authentification.(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
296
297 [[image:image2019-6-4_11-13-29.png]]
298
299 **Accès à une ressource sécurisée par un jeton JWT**
300 Pour que Swagger-ui offre la possibilité de saisir des informations d'authentification, il faut ajouter le package //(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)com.hardis.adelia.webservice(%%)(%%)(%%)// à la propriété (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)//resourcePackage//// //du bean //Swagger2Feature//(%%)(%%)(%%) (le package (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)//(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)com.hardis.adelia.webservice(%%)(%%)(%%)//(%%)(%%) contient un service factice qui permet d'ajouter une information de type //SwaggerSecurityDefinitions// dans le document swagger.json produit, information dont le contenu est ajustable en fonction de la propriété (//jaxrs:properties//) //SwaggerSecurityDefinitions// du point d'accès (//jaxrs:server//).
301 La propriété en question permet de choisir le type d'informations saisissables (jeton JWT et/ou HTTP Basic) via l'interface de //Swagger-ui//. Si aucune propriété n'est fixée alors, par défaut, l'interface propose un champ pour saisir un jeton JWT.
302 (%%)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
303 Pour déclarer de façon explicite les informations en lien avec un jeton JWT, il faut ajouter une entrée de type "jwt_key" avec la classe d'implémentation //io.swagger.models.auth.ApiKeyAuthDefinition// et les propriétés //name// et //in// prenant respectivement les valeurs //Authorization// et //HEADER//.
304 Exemple :
305 (%%)(%%)(%%)
306
307
308 {{code language="none"}}
309 <bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature" lazy-init="true">
310 <!~-~- ... -->
311 <property name="resourcePackage" value="com.hardis.adelia.webservice,hardis.fr" />
312 <!~-~- ... -->
313 </bean>
314
315
316 <jaxrs:server id="RestAdelia" address="/" transportId="http://cxf.apache.org/transports/http">
317 <jaxrs:features>
318 <ref bean="swagger2Feature" />
319 </jaxrs:features>
320 <jaxrs:properties>
321 <entry key="SwaggerSecurityDefinitions">
322 <map>
323 <entry key="jwt_Key">
324 <bean class="io.swagger.models.auth.ApiKeyAuthDefinition">
325 <property name="name" value="Authorization"/>
326 <property name="in">
327 <value type="io.swagger.models.auth.In">HEADER</value>
328 </property>
329 </bean>
330 </entry>
331 </map>
332 </entry>
333 </jaxrs:properties>
334 </jaxrs:server>
335 {{/code}}
336
337
338
339 (% style="color: rgb(0,0,0);" %)
340 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La configuration proposée ci-dessus a pour effet de modifier le //swagger.json// produit ; Swagger-ui adapte alors son interface en proposant un bouton [Authorize] (et des pictogrammes "cadenas" pour chaque méthode) ouvrant une fenêtre dans laquelle il est possible de saisir le jeton JWT. Par la suite ce jeton sera ajouté au header //Authorization// des requêtes d'accès aux ressources.
341
342 (%%)(%%)
343
344 (% style="color: rgb(0,0,0);" %)
345 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)[[image:image2018-3-29 18:43:11.png||height="250px"]]
346
347
348 (%%)(%%)
349
350 (% style="color: rgb(0,0,0);" %)
351 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)**Accès à une ressource sécurisée par une authentification HTTP Basic**(%%)(%%)(%%)(%%)
352
353 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)Pour que //Swagger-ui// offre la possibilité de saisir des informations d'authentification, il faut ajouter le package //(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)com.hardis.adelia.webservice(%%)(%%)(%%)// à la propriété (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)//resourcePackage//// //du bean //Swagger2Feature//(%%)(%%)(%%).
354 Pour choisir le type d'informations saisissables (jeton JWT et/ou HTTP Basic), il faut ajouter une propriété //SwaggerSecurityDefinitions// au //jaxrs:server//.
355 (%%)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
356 Pour des informations en lien avec une authentification HTTP Basic, il faut ajouter une entrée de type "basic_key" avec la classe d'implémentation //io.swagger.models.auth.BasicAuthDefinition//
357
358 Exemple :
359 (%%)(%%)(%%)(%%)(%%)
360
361
362 {{code language="none"}}
363 <bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature" lazy-init="true">
364 <!~-~- ... -->
365 <property name="resourcePackage" value="com.hardis.adelia.webservice,hardis.fr" />
366 <!~-~- ... -->
367 </bean>
368
369
370 <jaxrs:server id="RestAdelia" address="/" transportId="http://cxf.apache.org/transports/http">
371 <jaxrs:features>
372 <ref bean="swagger2Feature" />
373 </jaxrs:features>
374 <jaxrs:properties>
375 <entry key="SwaggerSecurityDefinitions">
376 <map>
377 <entry key="basic_Key">
378 <bean class="io.swagger.models.auth.BasicAuthDefinition" />
379 </entry>
380 </map>
381 </entry>
382 </jaxrs:properties>
383 </jaxrs:server>
384 {{/code}}
385
386 (% style="color: rgb(0,0,0);" %)
387 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)(% style="color: rgb(0,0,255);" %)(%%)****
388 ****(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La configuration proposée ci-dessus a pour effet de modifier le //swagger.json// produit ; //Swagger-u//i adapte alors son interface en proposant un bouton [Authorize] (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)(et des pictogrammes "cadenas" pour chaque méthode) (%%)(%%)ouvrant une fenêtre dans laquelle il est possible de saisir un //Username// et un //Password// pour alimenter le header //Authorization// des requêtes d'accès aux ressources.
389 (%%)(%%)
390 (%%)(%%)(%%)(%%)(%%)(%%)
391
392 (% style="color: rgb(0,0,0);" %)
393 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)[[image:image2018-3-30 10:19:6.png||height="250px"]](%%)(%%)
394
395 (% style="color: rgb(0,0,0);" %)
396 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
397
398 **Points d'accès multiples avec des contextes Swagger spécifiques**
399 ****Par défaut Swagger (via la feature Swagger2Feature) gère un contexte unique. Le document swagger.json produit prend en compte l'ensemble des ressources des différents points d'accès.
400 Il est possible d'associer un contexte Swagger spécifique à un point d'accès à l'aide des propriétés //usePathBasedConfig// et //scan// du bean //Swagger2Feature//.(%%)(%%)
401
402 (% style="color: rgb(0,0,0);" %)
403 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
404 Exemple
405 (%%)(%%)
406
407
408 {{code language="xml" title="beans.xml" language="xml"}}
409 <bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature" lazy-init="true">
410 <property name="supportSwaggerUi" value="true"/>
411 <property name="usePathBasedConfig" value="true"/>
412 <property name="scan" value="false"/>
413 <!~-~- ... -->
414 </bean>
415
416
417 <jaxrs:server id="rest1" address="/rs1" transportId="http://cxf.apache.org/transports/http" basePackages="com.hardis.adelia.webservice,hardis.jaxrs1">
418 <jaxrs:features>
419 <ref bean="swagger2Feature" />
420 </jaxrs:features>
421 </jaxrs:server>
422
423 <jaxrs:server id="rest2" address="/rs2" transportId="http://cxf.apache.org/transports/http" basePackages="com.hardis.adelia.webservice,hardis.jaxrs2">
424 <jaxrs:features>
425 <ref bean="swagger2Feature" />
426 </jaxrs:features>
427 </jaxrs:server>
428 {{/code}}
429
430 (% style="color: rgb(0,0,0);" %)
431 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
432
433 Le fichier //beans.xml// ci-dessus déclare 2 points d'accès (//rest1// et //rest2//). Les <//jaxrs:server//>utilisent l'attrbut //basePackages// pour détecter automatiquement les ressources et providers.
434 Remarque : Dans les cas précédents; la détection était réalisée à l'aide de la balise //<context:component-scan base-package~="package1, package2, ..."/>//.
435 Chaque point d'accès fait référence à la feature //Swagger2Feature// fixant la propriété(%%)(%%) //usePathBasedConfig// à //true// et la propriété //scan// à //false//.
436
437 (% style="color: rgb(0,0,0);" %)
438 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
439 Les points d'accès exposés sont les suivants :
440 (%%)(%%)
441
442 (% style="color: rgb(0,0,0);" %)
443 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)[[image:image2019-6-4_12-2-9.png||height="250px"]]
444
445 L'url de l'api-docs du point d'accès //rest1// permet d'afficher la page suivante :
446 [[image:image2019-6-4_12-10-49.png||height="250px"]]
447
448 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)L'url de l'api-docs du point d'accès //rest2// permet d'afficher la page suivante : (%%)(%%)
449 [[image:image2019-6-4_12-11-26.png||height="250px"]]
450 (%%)(%%)
451
452
453
454 **WADL**
455 ****Pour obtenir une description des services au format //WADL//, il faut déployer la librairie **cxf-rt-rs-service-description-3.x.y.jar **dans WEB-INF/lib de la webapp.
456 L'URL d'accès aux endpoints proposera alors des liens pour récupérer la description des services au format WADL.
457
458 Exemple****
459 **[[image:image2019-6-4_14-31-36.png||height="400px"]]**
460
461
462
463 L'URL d'accès au WADL au point d'accès rs1 permet de récupérer le document suivant :
464
465
466
467 {{code language="xml" title="rs1.xml" language="xml"}}
468 <application xmlns="http://wadl.dev.java.net/2009/02" xmlns:xs="http://www.w3.org/2001/XMLSchema">
469 <grammars/>
470 <resources base="http://localhost:8080/jaxrs/ws/rs1">
471 <resource path="/public/jx1pg1">
472 <resource path="/alpha/{in}">
473 <param name="in" style="template" type="xs:string"/>
474 <method name="GET">
475 <request/>
476 <response>
477 <representation mediaType="text/plain"/>
478 </response>
479 </method>
480 </resource>
481 </resource>
482 <resource path="/swagger.{type:json|yaml}">
483 <param name="type" style="template" type="xs:string"/>
484 <method name="GET">
485 <request/>
486 <response>
487 <representation mediaType="application/json"/>
488 <representation mediaType="application/yaml"/>
489 </response>
490 </method>
491 </resource>
492 <resource path="/api-docs">
493 <resource path="/{resource:.*}">
494 <param name="resource" style="template" type="xs:string"/>
495 <method name="GET">
496 <request/>
497 <response>
498 <representation mediaType="*/*"/>
499 </response>
500 </method>
501 </resource>
502 </resource>
503 </resources>
504 </application>
505 {{/code}}
506
507
508
509 (((
510 = ((% style="color: rgb(255,0,0);" %)V14 PTF01(%%)) =
511 )))
512 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF01 intègre les librairies : (%%)(%%)
513 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.1.18(%%)(%%)
514 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 1.5.22(%%)(%%)
515 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.ui 3.20(%%)(%%)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %).9(%%)(%%)
516
517 (((
518 = ((% style="color: rgb(255,0,0);" %)V14 PTF02(%%)) =
519 )))
520 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF02 intègre les librairies : (%%)(%%)
521 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.3.4(%%)(%%)
522 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 1.6.0(%%)(%%)
523 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.ui 3.24(%%)(%%)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %).3(%%)(%%)
524
525 (((
526 = ((% style="color: rgb(255,0,0);" %)V14 PTF04(%%)) =
527 )))
528 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF04 intègre les librairies : (%%)(%%)
529 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.3.8(%%)(%%)
530 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 1.6.2(%%)(%%)
531 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.ui 3.38(%%)(%%)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %).0(%%)(%%)
532
533 (((
534 = ((% style="color: rgb(255,0,0);" %)V14 PTF07(%%)) =
535 )))
536 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF07 intègre les librairies : (%%)(%%)
537 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.3.13(%%)(%%)
538 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 1.6.6(%%)(%%)
539 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.ui 3.52(%%)(%%)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %).5
540 (%%)(%%)
541
542 (((
543 = ((% style="color: rgb(255,0,0);" %)V14 PTF08 Fix02(%%)) =
544 )))
545 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)Evolution **(% style="color: rgb(23,43,77);" %)_(%%)(% style="color: rgb(23,43,77);" %)swag_response(%%)**
546 Possibilité de spécifier :
547 (%%)(%%)
548 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)le nom d'une variable résultat pour préciser le schéma/modèle de la réponse (Note : par défaut c'est celui de la variable paramètre portant la définition //o[Content]//) pour le code HTTP donné(%%)(%%)
549 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)*NONE pour ne pas associer de schéma/modèle pour le code HTTP donné(%%)(%%)
550
551 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)SW_CONFIGURER *OPERATION _WS_REST_SWAG_RESPONSE 'ResultVarName:CodeHttp:Description' → le schéma/modèle est celui ResultVarName
552 SW_CONFIGURER *OPERATION _WS_REST_SWAG_RESPONSE '*NONE:CodeHttp:Description'(%%)(%%) (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)→ aucun schéma/modèle(%%)(%%)
553 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)SW_CONFIGURER *OPERATION _WS_REST_SWAG_RESPONSE 'CodeHttp:Description' → le schéma/modèle est celui de la variable paramètre définie en o[Content]
554 (%%)(%%)
555 (((
556 = ((% style="color: rgb(255,0,0);" %)V14 PTF09(%%)) =
557 )))
558 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF09 intègre les librairies : (%%)(%%)
559 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.4.10
560 (%%)(%%)
561 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 2.2.10(%%)(%%)
562 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.ui 4.18.2
563 (%%)(%%)
564
565 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)**Abandon de la spécification Swagger2(OpenApi2) au profit d'OpenApi3.**
566 Les beans //Swagger2Feature, Swagger2FeatureExtended, SwaggJaxbInit //sont dépréciés et doivent être supprimés du fichier //beans.xml//.
567 Il faut désormais utiliser l'unique bean //com.hardis.adelia.webservice.OpenApiFeatureExtended//. Ce composant hérite du composant OpenApiFeature dont les propriétés sont détaillées ici : [[https://cxf.apache.org/docs/openapifeature.html>>url:https://cxf.apache.org/docs/openapifeature.html]]
568
569 Exemple :
570 (%%)(%%)
571
572
573 {{code language="xml" title="beans.xml" language="xml"}}
574 <!~-~- Liste des ressources REST : définition des packages à scanner -->
575 <!~-~- Note : le package com.hardis.adelia.webservice doit toujours figurer dans la liste : -->
576 <!~-~- - Permet de définir le serveur par défaut à partir du basePath -->
577 <!~-~- - Permet de définir un SecurityScheme (JWT) pour assurer une authentification via un jeton JWT -->
578 <context:component-scan base-package="com.hardis.adelia.webservice,local.test"/>
579
580 <!~-~- Configuration du bean openApiFeature -->
581 <!~-~- basePath : <ContextRoot>/<CXFServletMapping> -->
582 <bean id="openApiFeature" class="com.hardis.adelia.webservice.OpenApiFeatureExtented" lazy-init="true">
583 <property name="basePath" value="/jaxrs/ws" />
584 <property name="swguicfg_core_queryConfigEnabled" value="false" />
585 <property name="title" value="REST API - OPENAPIFEATURE" />
586 <property name="description" value="REST Api 2.0 OpenApiFeature description list" />
587 <property name="version" value="2.0" />
588 <property name="supportSwaggerUi" value="true"/>
589 </bean>
590
591 <jaxrs:server id="rest" address="/" transportId="http://cxf.apache.org/transports/http">
592 <jaxrs:features>
593 <!~-~- déclaration de l'utilisation de l'openApiFeature -->      
594 <ref bean="openApiFeature" />
595 </jaxrs:features>
596 </jaxrs:server>
597
598 {{/code}}
599
600 **IMPORTANT : **
601 * **(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)OpenApi3(%%)(%%) **a son propre jeu d'annotations aussi est-il nécessaire de regénérer les programmes de services web REST et les classes associées pour bénéficier de la documentation SwaggerUi.
602 * En cas d'utiliation combinée de **swaggerUi** et de l'authentification **JWT **- il faut ajouter à l'attribut //(% style="color: rgb(0,51,102);" %)jwtSwaggerURI (%%)//(% style="color: rgb(0,51,102);" %)du bean (%%)//(% style="color: rgb(0,51,102);" %)jwtTokenConfiguration(%%)//(% style="color: rgb(0,51,102);" %)(% style="color: rgb(0,51,102);" %) la séquence ///ws/openapi*//
603 //Exemple : //
604 ////(%%)(%%)
605
606
607 {{code title="Beans.xml - jwtTokenConfiguration - OpenApi" language="none"}}
608 <bean id="jwtTokenConfiguration" class="com.hardis.adelia.webservice.JwtTokenConfiguration">
609 <property name="jwtBasePath" value="/ws/*" />
610 <property name="jwtSwaggerURI" value="/ws/api-docs;/ws/swagger*;/ws/openapi*"/>              
611 ...
612 </bean>
613 {{/code}}
614
615
616
617 * La version embarquée de swaggerui (swagger-ui-4.18.2.jar) ne permet plus par défaut de passer des éléments de configuration de swaggerUI via des paramètres d'url. Seul le paramètre //url// est accepté sous condition de fixer la propriété //swguicfg_core_queryConfigEnabled //à la valeur //false //dans le bean //openApiFeature//.
618 Exemple :
619 [[http://localhost:8081/adelrestapp/ws/api-docs?>>url:http://localhost:8081/adelrestapp/ws/api-docs?url=/adelrestapp/ws/openapi.json]][[url~=/adelrestapp/ws/openapi.json>>url:http://localhost:8081/adelrestapp/ws/api-docs?url=/adelrestapp/ws/openapi.json]]
620
621 Pour passer des éléments de configuration il faut modifer le fichier //**swagger-initializer.js** (swagger-ui-4.18.2.jar~-~->/META-INF/resources/webjars/swagger-ui/4.18.2),//
622 ** soit en ajoutant au //SwaggerUIBundle// l'attribut// queryConfigEnabled:true// puis en passant les paramètres via l'URL
623 Exemple :
624 window.ui ~= SwaggerUIBundle({
625 url: "[[https://petstore.swagger.io/v2/swagger.json>>url:https://petstore.swagger.io/v2/swagger.json]]",
626 dom_id: '#swagger-ui',
627 deepLinking: true,
628 **queryConfigEnabled:true,**
629 presets: [...
630
631 [[http://localhost:8081/adelrestapp/ws/api-docs?>>url:http://localhost:8081/adelrestapp/ws/api-docs?url=/adelrestapp/ws/openapi.json]][[url~=/adelrestapp/ws/openapi.json>>url:http://localhost:8081/adelrestapp/ws/api-docs?url=/adelrestapp/ws/openapi.json]]**[[&docExpansion=none&tagsSorter=alpha&displayRequestDuration=true&filter=true&syntaxHighlight=false&defaultModelsExpandDepth=-1>>url:https://scsdc1rfxdlv001.hardis.fr/reflexWS/rest/api-docs?url=/reflexWS/rest/swagger.json&docExpansion=none&tagsSorter=alpha&displayRequestDuration=true&filter=true&syntaxHighlight=false&defaultModelsExpandDepth=-1]]
632 **
633 ** soit en ajoutant directement au //SwaggerUIBundle //l'ensemble des attributs voulus
634 Exemple:
635 window.ui ~= SwaggerUIBundle({
636 url: "[[https://petstore.swagger.io/v2/swagger.json>>url:https://petstore.swagger.io/v2/swagger.json]]",
637 dom_id: '#swagger-ui',
638 deepLinking: true,
639 **defaultModelsExpandDepth:-1,**
640 **** **displayRequestDuration:true,**
641 **** **docExpansion:'none',**
642 **** **filter:true,**
643 **** **tagsSorter:'alpha',**
644 **** **syntaxHighlight:false,**
645 presets: [...
646
647
648
649 * La propriété **resourcePackages **(permettant de filtrer via des noms des packages les apis affichées par swagger-ui) doit être utilisée conjointement avec la propriété **scan. **Pour activer le filtrage il faut désormais fixer la propriété **scan** à la valeur //false ; //dans le cas contraire tous les packages listés dans l'attribut //base-package //de l'élément **component-scan **sont systématiquement pris en compte.
650
651
652 * La présence du package //com.hardis.adelia.webservice //dans l'attribut //base-package// de l'élément //component-scan// permet d'enrichir automatiquement le fichier //openapi.json// construit - notamment pour donner la possibilité d'une authentification via un jeton JWT.
653 (% style="color: rgb(0,51,102);" %)<context:component-scan //base-package//~="**com.hardis.adelia.webservice**,..."/>(%%)
654 Il est possible de définir ses propres modes d'authentification (via des SecurityScheme) en ajoutant des propriétés au //jaxrs:server//
655 ////Exemple :
656
657
658
659 {{code language="none"}}
660 <bean id="openApiFeature" class="com.hardis.adelia.webservice.OpenApiFeatureExtended" lazy-init="true">
661 <!~-~- ... -->
662 </bean>
663
664 <jaxrs:server id="RestAdelia" address="/" transportId="http://cxf.apache.org/transports/http">
665 <jaxrs:features>
666 <ref bean="openApiFeature" />
667 </jaxrs:features>
668 <jaxrs:properties>  
669 <entry key="SwaggerSecurityDefinitions">
670 <map>
671 <entry key="jwt_Key">
672 <bean class="io.swagger.v3.oas.models.security.SecurityScheme" >
673 <property name="name" value="jwt_Key"/>
674 <property name="type">
675 <value type="io.swagger.v3.oas.models.security.SecurityScheme.Type">HTTP</value>
676 </property>
677 <property name="scheme" value="bearer"/>
678 <property name="bearerFormat" value="JWT"/>
679 </bean>
680 </entry>
681 <entry key="basic_Key">
682 <bean class="io.swagger.v3.oas.models.security.SecurityScheme" >
683 <property name="name" value="basic_Key"/>
684 <property name="type">
685 <value type="io.swagger.v3.oas.models.security.SecurityScheme.Type">HTTP</value>
686 </property>
687 <property name="scheme" value="basic"/>
688 </bean>
689 </entry>
690 </map>
691 </entry>  
692 </jaxrs:properties>
693 </jaxrs:server>
694 {{/code}}
695
696 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)****
697 **Ajout d'annotations permettant à swagger-ui d'afficher la définition Adélia des champs alpha et numérique :**(%%)(%%)
698 //maxLength// donne la longeur maximale (longueur Adélia) d'un champ alphanumérique
699 //minimum// et //maximum //donnent respectivement la borne inférieure et la borne supérieure d'un champ numérique selon sa définition Adélia.
700 **Mise en garde** : Swagger-UI n'affiche correctement que les entiers compris entre {{hardis-code}}-9007199254740991{{/hardis-code}} et {{hardis-code}}9007199254740991. Les entiers en dehors de cette plage ainsi que certains nombres décimaux peuvent faire l'objet d'un arrondi.
701
702 {{/hardis-code}}
703 (((
704 = ((% style="color: rgb(255,0,0);" %)V14 PTF10(%%)) =
705 )))
706 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF010 intègre les librairies : (%%)(%%)
707 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.4.10
708 (%%)(%%)
709 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 2.2.19(%%)(%%)
710 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.ui 5.10.3(%%)(%%)
711 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)springframework : 5.3.31(%%)(%%)
712
713
714
715 (((
716 = ((% style="color: rgb(255,0,0);" %)V14 PTF11(%%)) =
717 )))
718 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF011 intègre les librairies : (%%)(%%)
719 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.5.8
720 (%%)(%%)
721 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 2.2.22(%%)(%%)
722 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.ui 5.17.14(%%)(%%)
723 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)springframework : 5.3.36(%%)(%%)
724
725
726
727 (((
728 = ((% style="color: rgb(255,0,0);" %)V14 PTF12(%%)) =
729 )))
730 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF012 intègre les librairies : (%%)(%%)
731 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.5.10
732 (%%)(%%)
733 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 2.2.23(%%)(%%)
734 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.ui 5.18.2(%%)(%%)
735 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)springframework : 5.3.39(%%)(%%)
736
737
738