Skip to Content
Last modified by Administrateur local on 2024/12/18 11:00
Show last authors
1
2
3 Il est possible de paramétrer Swagger via le fichier de configuration Spring "///WEB-INF/beans.xml//" en déclarant :
4 (% style="color: rgb(0,0,255);" %)
5 * (% 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
6 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)Exemple :(%%)
7 (%%)(%%)
8
9
10 {{code language="none"}}
11 <bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature" lazy-init="true">
12 <property name="basePath" value="/jaxrs/ws"/>
13 <property name="resourcePackage" value="hardis.jaxrs"/>
14 <property name="contact" value="hotline.adelia@hardis.fr" />
15 <property name="title" value="REST Services List" />
16 <property name="description" value="REST services documentation" />
17 <property name="version" value="2.1" />
18 <property name="termsOfServiceUrl" value="http://www.hardis-group.com" />
19 </bean>
20 {{/code}}
21
22
23 (% style="color: rgb(0,0,255);" %)
24 (% 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).(%%)(%%)
25 (%%)
26
27
28 {{code language="xml" language="xml"}}
29 <jaxrs:server id="rest" address="/" transportId="http://cxf.apache.org/transports/http">
30 <jaxrs:features>
31 <ref bean="swagger2Feature" />
32 </jaxrs:features>
33 </jaxrs:server>
34 {{/code}}
35
36
37
38 (% style="color: rgb(0,0,255);" %)
39 Détail des propriétés de la feature Swagger2Feature
40 (%%)
41 |=(% colspan="1" rowspan="1" %)(((
42 Name)))|=(% colspan="1" rowspan="1" %)(((
43 Description)))|=(% colspan="1" rowspan="1" %)(((
44 Default)))
45 |(% colspan="1" rowspan="1" %)(((
46 basePath)))|(% colspan="1" rowspan="1" %)(((
47 the context root path+)))|(% colspan="1" rowspan="1" %)(((
48 null)))
49 |(% colspan="1" rowspan="1" %)(((
50 contact)))|(% colspan="1" rowspan="1" %)(((
51 the contact information+)))|(% colspan="1" rowspan="1" %)(((
52 "users@[[cxf.apache.org>>url:http://cxf.apache.org]]")))
53 |(% colspan="1" rowspan="1" %)(((
54 description)))|(% colspan="1" rowspan="1" %)(((
55 the description+)))|(% colspan="1" rowspan="1" %)(((
56 "The Application")))
57 |(% colspan="1" rowspan="1" %)(((
58 filterClass)))|(% colspan="1" rowspan="1" %)(((
59 a security filter+)))|(% colspan="1" rowspan="1" %)(((
60 null)))
61 |(% colspan="1" rowspan="1" %)(((
62 host)))|(% colspan="1" rowspan="1" %)(((
63 the host and port+)))|(% colspan="1" rowspan="1" %)(((
64 null)))
65 |(% colspan="1" rowspan="1" %)(((
66 ignoreRoutes)))|(% colspan="1" rowspan="1" %)(((
67 excludes specific paths when scanning all resources (see scanAllResources)++)))|(% colspan="1" rowspan="1" %)(((
68 null)))
69 |(% colspan="1" rowspan="1" %)(((
70 license)))|(% colspan="1" rowspan="1" %)(((
71 the license+)))|(% colspan="1" rowspan="1" %)(((
72 "Apache 2.0 License")))
73 |(% colspan="1" rowspan="1" %)(((
74 licenceUrl)))|(% colspan="1" rowspan="1" %)(((
75 the license URL+)))|(% colspan="1" rowspan="1" %)(((
76 "[[http://www.apache.org/licenses/LICENSE-2.0.html>>url:http://www.apache.org/licenses/LICENSE-2.0.html]]")))
77 |(% colspan="1" rowspan="1" %)(((
78 prettyPrint)))|(% colspan="1" rowspan="1" %)(((
79 when generating swagger.json, pretty-print the json document+)))|(% colspan="1" rowspan="1" %)(((
80 false)))
81 |(% colspan="1" rowspan="1" %)(((
82 resourcePackage)))|(% colspan="1" rowspan="1" %)(((
83 a list of comma separated package names where resources must be scanned+)))|(% colspan="1" rowspan="1" %)(((
84 a list of service classes configured at the endpoint)))
85 |(% colspan="1" rowspan="1" %)(((
86 runAsFilter)))|(% colspan="1" rowspan="1" %)(((
87 runs the feature as a filter)))|(% colspan="1" rowspan="1" %)(((
88 false)))
89 |(% colspan="1" rowspan="1" %)(((
90 scan)))|(% colspan="1" rowspan="1" %)(((
91 generates the swagger documentation+)))|(% colspan="1" rowspan="1" %)(((
92 true)))
93 |(% colspan="1" rowspan="1" %)(((
94 scanAllResources)))|(% colspan="1" rowspan="1" %)(((
95 scans all resources including non-annotated JAX-RS resources++)))|(% colspan="1" rowspan="1" %)(((
96 false)))
97 |(% colspan="1" rowspan="1" %)(((
98 schemes)))|(% colspan="1" rowspan="1" %)(((
99 the protocol schemes+)))|(% colspan="1" rowspan="1" %)(((
100 null)))
101 |(% colspan="1" rowspan="1" %)(((
102 termsOfServiceUrl)))|(% colspan="1" rowspan="1" %)(((
103 the terms of service URL+)))|(% colspan="1" rowspan="1" %)(((
104 null)))
105 |(% colspan="1" rowspan="1" %)(((
106 title)))|(% colspan="1" rowspan="1" %)(((
107 the title+)))|(% colspan="1" rowspan="1" %)(((
108 "Sample REST Application")))
109 |(% colspan="1" rowspan="1" %)(((
110 version)))|(% colspan="1" rowspan="1" %)(((
111 the version+)))|(% colspan="1" rowspan="1" %)(((
112 "1.0.0")))
113
114
115 (% style="color: rgb(0,0,255);" %)Remarques :
116 (%%)
117 (% style="color: rgb(0,0,255);" %)
118 * (% 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.(%%)
119 (% style="color: rgb(0,0,255);" %)
120 * 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.(%%)
121 (% style="color: rgb(0,0,255);" %)
122 * (% style="color: rgb(0,0,255);" %)La propriété basePath n'est plus utile car calculée automatiquement.
123 (%%)
124
125
126 (% style="color: rgb(0,0,255);" %)
127 (%%)(% 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).
128
129 Exemple :(%%)
130 (%%)
131
132
133 {{code language="none"}}
134 <bean id="SwaggJaxbInit" class="com.hardis.adelia.webservice.SwaggJaxbInit" init-method="init" >
135 <property name="jaxbMapper" value="true"/>
136 <property name="serializeWRAP_ROOT_VALUE" value="false"/>
137 <property name="serializeWRITE_DATES_AS_TIMESTAMPS" value="true"/>
138 <property name="serializeWRITE_DATE_KEYS_AS_TIMESTAMPS" value="false"/>
139 <property name="serializeWRITE_CHAR_ARRAYS_AS_JSON_ARRAYS" value="false"/>
140 <property name="serializeWRITE_EMPTY_JSON_ARRAYS" value="true"/>
141 <property name="serializeWRITE_SINGLE_ELEM_ARRAYS_UNWRAPPED" value="false"/>
142 <property name="deserializeUSE_JAVA_ARRAY_FOR_JSON_ARRAY" value="false"/>
143 <property name="deserializeACCEPT_SINGLE_VALUE_AS_ARRAY" value="false"/>
144 <property name="deserializeUNWRAP_ROOT_VALUE" value="false"/>
145 <property name="deserializeUNWRAP_SINGLE_VALUE_ARRAYS" value="false"/>
146 <property name="deserializeFAIL_ON_IGNORED_PROPERTIES" value="false"/>
147 <property name="deserializeFAIL_ON_UNKNOWN_PROPERTIES" value="true"/>
148 </bean>
149 {{/code}}
150
151
152 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)Les détails sur les propriétés se trouvent (%%):
153 [[https://github.com/FasterXML/jackson-databind/wiki/Serialization-features>>url:https://github.com/FasterXML/jackson-databind/wiki/Serialization-features]]
154 [[https://github.com/FasterXML/jackson-databind/wiki/Deserialization-Feature>>url:https://github.com/FasterXML/jackson-databind/wiki/Deserialization-Features]](%%)
155 (((
156 = ((% style="color: rgb(255,0,0);" %)V13 PTF9(%%)) =
157 )))
158
159 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V13 PTF09 intègre les librairies : (%%)(%%)
160 (% style="color: rgb(0,0,0);" %)
161 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.1.6(%%)(%%)
162 (% style="color: rgb(0,0,0);" %)
163 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 1.5.9(%%)(%%)
164 (% style="color: rgb(0,0,0);" %)
165 * (% 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
166 (%%)(%%)
167
168 (((
169 = ((% style="color: rgb(255,0,0);" %)V14 PTF00(%%)) =
170 )))
171
172 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF00 intègre les librairies : (%%)(%%)
173 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.1.17(%%)(%%)
174 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 1.5.18(%%)(%%)
175 * (% 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(%%)(%%)
176
177
178 (% style="color: rgb(0,0,0);" %)
179 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
180 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//.
181 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.(%%)(%%)
182
183 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**
184
185 Exemple :
186
187 [[image:image2019-6-4_10-58-13.png]]
188
189
190 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**.
191 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.
192 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]]
193 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.
194
195 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.
196 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//).
197 (% 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.(%%)(%%)
198
199 Exemple (//index.html//; ajout dans le header //Authorization// du jeton passé dans l'URL via un paramètre nommé //apiKey//:
200 (%%)(%%)
201
202
203 {{code language="js" title="index.html" language="js"}}
204 <script>
205 function getUrlParameter(name) {
206 name = name.replace(/[\[]/, '\\[').replace(/[\]]/, '\\]');
207 var regex = new RegExp('[\\?&]' + name + '=([^&#]*)');
208 var results = regex.exec(location.search);
209 return results === null ? '' : decodeURIComponent(results[1].replace(/\+/g, ' '));
210 };
211
212 var apiKey = getUrlParameter('apiKey');
213
214 window.onload = function() {
215 // Begin Swagger UI call region
216 const ui = SwaggerUIBundle({
217 url: "/jaxrs/ws/swagger.json",
218 dom_id: '#swagger-ui',
219 deepLinking: true,
220 validatorUrl:null,
221 presets: [
222 SwaggerUIBundle.presets.apis,
223 SwaggerUIStandalonePreset
224 ],
225 plugins: [
226 SwaggerUIBundle.plugins.DownloadUrl
227 ],
228 layout: "StandaloneLayout",
229
230 requestInterceptor: function(request) {
231 request.headers.Authorization = "JWT " + apiKey;
232 return request;
233 }
234 })
235 {{/code}}
236
237
238
239 (% style="color: rgb(0,0,0);" %)
240 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
241 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 (%%)(%%):
242
243 [[image:image2019-6-4_11-10-0.png]]
244
245
246 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.
247 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.
248 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);" %)
249
250 [[image:image2019-6-4_11-13-29.png]]
251
252 **Accès à une ressource sécurisée par un jeton JWT**
253 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//).
254 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.
255 (%%)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
256 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//.
257 Exemple :
258 (%%)(%%)(%%)
259
260
261 {{code language="none"}}
262 <bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature" lazy-init="true">
263 <!-- ... -->
264 <property name="resourcePackage" value="com.hardis.adelia.webservice,hardis.fr" />
265 <!-- ... -->
266 </bean>
267
268
269 <jaxrs:server id="RestAdelia" address="/" transportId="http://cxf.apache.org/transports/http">
270 <jaxrs:features>
271 <ref bean="swagger2Feature" />
272 </jaxrs:features>
273 <jaxrs:properties>
274 <entry key="SwaggerSecurityDefinitions">
275 <map>
276 <entry key="jwt_Key">
277 <bean class="io.swagger.models.auth.ApiKeyAuthDefinition">
278 <property name="name" value="Authorization"/>
279 <property name="in">
280 <value type="io.swagger.models.auth.In">HEADER</value>
281 </property>
282 </bean>
283 </entry>
284 </map>
285 </entry>
286 </jaxrs:properties>
287 </jaxrs:server>
288 {{/code}}
289
290
291
292 (% style="color: rgb(0,0,0);" %)
293 (% 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.
294
295 (%%)(%%)
296
297 (% style="color: rgb(0,0,0);" %)
298 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)[[image:image2018-3-29 18:43:11.png||height="250"]]
299
300
301 (%%)(%%)
302
303 (% style="color: rgb(0,0,0);" %)
304 (% 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**(%%)(%%)(%%)(%%)
305
306 (% 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//(%%)(%%)(%%).
307 Pour choisir le type d'informations saisissables (jeton JWT et/ou HTTP Basic), il faut ajouter une propriété //SwaggerSecurityDefinitions// au //jaxrs:server//.
308 (%%)(% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
309 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//
310
311 Exemple :
312 (%%)(%%)(%%)(%%)(%%)
313
314
315 {{code language="none"}}
316 <bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature" lazy-init="true">
317 <!-- ... -->
318 <property name="resourcePackage" value="com.hardis.adelia.webservice,hardis.fr" />
319 <!-- ... -->
320 </bean>
321
322
323 <jaxrs:server id="RestAdelia" address="/" transportId="http://cxf.apache.org/transports/http">
324 <jaxrs:features>
325 <ref bean="swagger2Feature" />
326 </jaxrs:features>
327 <jaxrs:properties>
328 <entry key="SwaggerSecurityDefinitions">
329 <map>
330 <entry key="basic_Key">
331 <bean class="io.swagger.models.auth.BasicAuthDefinition" />
332 </entry>
333 </map>
334 </entry>
335 </jaxrs:properties>
336 </jaxrs:server>
337 {{/code}}
338
339
340 (% style="color: rgb(0,0,0);" %)
341 (% 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);" %)(%%)**
342 **(% 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.
343 (%%)(%%)
344 (%%)(%%)(%%)(%%)(%%)(%%)
345
346 (% style="color: rgb(0,0,0);" %)
347 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)[[image:image2018-3-30 10:19:6.png||height="250"]](%%)(%%)
348
349 (% style="color: rgb(0,0,0);" %)
350 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
351
352 **Points d'accès multiples avec des contextes Swagger spécifiques
353 **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.
354 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//.(%%)(%%)
355
356 (% style="color: rgb(0,0,0);" %)
357 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
358 Exemple
359 (%%)(%%)
360
361
362 {{code language="xml" title="beans.xml" language="xml"}}
363 <bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature" lazy-init="true">
364 <property name="supportSwaggerUi" value="true"/>
365 <property name="usePathBasedConfig" value="true"/>
366 <property name="scan" value="false"/>
367 <!-- ... -->
368 </bean>
369
370
371 <jaxrs:server id="rest1" address="/rs1" transportId="http://cxf.apache.org/transports/http" basePackages="com.hardis.adelia.webservice,hardis.jaxrs1">
372 <jaxrs:features>
373 <ref bean="swagger2Feature" />
374 </jaxrs:features>
375 </jaxrs:server>
376
377 <jaxrs:server id="rest2" address="/rs2" transportId="http://cxf.apache.org/transports/http" basePackages="com.hardis.adelia.webservice,hardis.jaxrs2">
378 <jaxrs:features>
379 <ref bean="swagger2Feature" />
380 </jaxrs:features>
381 </jaxrs:server>
382 {{/code}}
383
384
385 (% style="color: rgb(0,0,0);" %)
386 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
387
388 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.
389 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, ..."/>//.
390 Chaque point d'accès fait référence à la feature //Swagger2Feature// fixant la propriété(%%)(%%) //usePathBasedConfig// à //true// et la propriété //scan// à //false//.
391
392 (% style="color: rgb(0,0,0);" %)
393 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)
394 Les points d'accès exposés sont les suivants :
395 (%%)(%%)
396
397 (% style="color: rgb(0,0,0);" %)
398 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)[[image:image2019-6-4_12-2-9.png||height="250"]]
399
400 L'url de l'api-docs du point d'accès //rest1// permet d'afficher la page suivante :
401 [[image:image2019-6-4_12-10-49.png||height="250"]]
402
403 (% 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 : (%%)(%%)
404 [[image:image2019-6-4_12-11-26.png||height="250"]]
405 (%%)(%%)
406
407
408 **WADL
409 **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.
410 L'URL d'accès aux endpoints proposera alors des liens pour récupérer la description des services au format WADL.
411
412 Exemple**
413 [[image:image2019-6-4_14-31-36.png||height="400"]]**
414
415
416 L'URL d'accès au WADL au point d'accès rs1 permet de récupérer le document suivant :
417
418
419
420 {{code language="xml" title="rs1.xml" language="xml"}}
421 <application xmlns="http://wadl.dev.java.net/2009/02" xmlns:xs="http://www.w3.org/2001/XMLSchema">
422 <grammars/>
423 <resources base="http://localhost:8080/jaxrs/ws/rs1">
424 <resource path="/public/jx1pg1">
425 <resource path="/alpha/{in}">
426 <param name="in" style="template" type="xs:string"/>
427 <method name="GET">
428 <request/>
429 <response>
430 <representation mediaType="text/plain"/>
431 </response>
432 </method>
433 </resource>
434 </resource>
435 <resource path="/swagger.{type:json|yaml}">
436 <param name="type" style="template" type="xs:string"/>
437 <method name="GET">
438 <request/>
439 <response>
440 <representation mediaType="application/json"/>
441 <representation mediaType="application/yaml"/>
442 </response>
443 </method>
444 </resource>
445 <resource path="/api-docs">
446 <resource path="/{resource:.*}">
447 <param name="resource" style="template" type="xs:string"/>
448 <method name="GET">
449 <request/>
450 <response>
451 <representation mediaType="*/*"/>
452 </response>
453 </method>
454 </resource>
455 </resource>
456 </resources>
457 </application>
458 {{/code}}
459
460
461
462
463 (((
464 = ((% style="color: rgb(255,0,0);" %)V14 PTF01(%%)) =
465 )))
466
467 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF01 intègre les librairies : (%%)(%%)
468 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.1.18(%%)(%%)
469 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 1.5.22(%%)(%%)
470 * (% 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(%%)(%%)
471
472 (((
473 = ((% style="color: rgb(255,0,0);" %)V14 PTF02(%%)) =
474 )))
475
476 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF02 intègre les librairies : (%%)(%%)
477 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.3.4(%%)(%%)
478 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 1.6.0(%%)(%%)
479 * (% 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(%%)(%%)
480
481 (((
482 = ((% style="color: rgb(255,0,0);" %)V14 PTF04(%%)) =
483 )))
484
485 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF04 intègre les librairies : (%%)(%%)
486 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.3.8(%%)(%%)
487 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 1.6.2(%%)(%%)
488 * (% 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(%%)(%%)
489
490 (((
491 = ((% style="color: rgb(255,0,0);" %)V14 PTF07(%%)) =
492 )))
493
494 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF07 intègre les librairies : (%%)(%%)
495 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.3.13(%%)(%%)
496 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 1.6.6(%%)(%%)
497 * (% 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
498 (%%)(%%)
499
500 (((
501 = ((% style="color: rgb(255,0,0);" %)V14 PTF08 Fix02(%%)) =
502 )))
503
504 (% 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(%%)**
505 Possibilité de spécifier :
506 (%%)(%%)
507 * (% 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é(%%)(%%)
508 * (% 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é(%%)(%%)
509
510
511 (% 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
512 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(%%)(%%)
513 (% 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]
514 (%%)(%%)
515 (((
516 = ((% style="color: rgb(255,0,0);" %)V14 PTF09(%%)) =
517 )))
518
519 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF09 intègre les librairies : (%%)(%%)
520 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.4.10
521 (%%)(%%)
522 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 2.2.10(%%)(%%)
523 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.ui 4.18.2
524 (%%)(%%)
525
526
527 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)**Abandon de la spécification Swagger2(OpenApi2) au profit d'OpenApi3.**
528 Les beans //Swagger2Feature, Swagger2FeatureExtended, SwaggJaxbInit //sont dépréciés et doivent être supprimés du fichier //beans.xml//.
529 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]]
530
531 Exemple :
532 (%%)(%%)
533
534
535 {{code language="xml" title="beans.xml" language="xml"}}
536 <!-- Liste des ressources REST : définition des packages à scanner -->
537 <!-- Note : le package com.hardis.adelia.webservice doit toujours figurer dans la liste : -->
538 <!-- - Permet de définir le serveur par défaut à partir du basePath -->
539 <!-- - Permet de définir un SecurityScheme (JWT) pour assurer une authentification via un jeton JWT -->
540 <context:component-scan base-package="com.hardis.adelia.webservice,local.test"/>
541
542 <!-- Configuration du bean openApiFeature -->
543 <!-- basePath : <ContextRoot>/<CXFServletMapping> -->
544 <bean id="openApiFeature" class="com.hardis.adelia.webservice.OpenApiFeatureExtented" lazy-init="true">
545 <property name="basePath" value="/jaxrs/ws" />
546 <property name="swguicfg_core_queryConfigEnabled" value="false" />
547 <property name="title" value="REST API - OPENAPIFEATURE" />
548 <property name="description" value="REST Api 2.0 OpenApiFeature description list" />
549 <property name="version" value="2.0" />
550 <property name="supportSwaggerUi" value="true"/>
551 </bean>
552
553 <jaxrs:server id="rest" address="/" transportId="http://cxf.apache.org/transports/http">
554 <jaxrs:features>
555 <!-- déclaration de l'utilisation de l'openApiFeature -->      
556 <ref bean="openApiFeature" />
557 </jaxrs:features>
558 </jaxrs:server>
559
560 {{/code}}
561
562
563 **IMPORTANT : **
564 * **(% 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.
565 * 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*
566 Exemple :
567 //(%%)(%%)
568
569
570 {{code title="Beans.xml - jwtTokenConfiguration - OpenApi" language="none"}}
571 <bean id="jwtTokenConfiguration" class="com.hardis.adelia.webservice.JwtTokenConfiguration">
572 <property name="jwtBasePath" value="/ws/*" />
573 <property name="jwtSwaggerURI" value="/ws/api-docs;/ws/swagger*;/ws/openapi*"/>              
574 ...
575 </bean>
576 {{/code}}
577
578
579
580 * 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//.
581 Exemple :
582 [[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]]
583
584 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),//** soit en ajoutant au //SwaggerUIBundle// l'attribut// queryConfigEnabled:true// puis en passant les paramètres via l'URL
585 Exemple :
586 window.ui ~= SwaggerUIBundle({
587 url: "[[https://petstore.swagger.io/v2/swagger.json>>url:https://petstore.swagger.io/v2/swagger.json]]",
588 dom_id: '#swagger-ui',
589 deepLinking: true,
590 **queryConfigEnabled:true,**
591 presets: [...
592
593 [[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]]
594 **
595 ** soit en ajoutant directement au //SwaggerUIBundle //l'ensemble des attributs voulus
596 Exemple:
597 window.ui ~= SwaggerUIBundle({
598 url: "[[https://petstore.swagger.io/v2/swagger.json>>url:https://petstore.swagger.io/v2/swagger.json]]",
599 dom_id: '#swagger-ui',
600 deepLinking: true,
601 ** defaultModelsExpandDepth:-1,
602 **** displayRequestDuration:true,
603 **** docExpansion:'none',
604 **** filter:true,
605 **** tagsSorter:'alpha',
606 **** syntaxHighlight:false,**
607 presets: [...
608
609
610
611 * 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.
612
613
614 * 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.
615
616 (% style="color: rgb(0,51,102);" %)<context:component-scan //base-package//~="**com.hardis.adelia.webservice**,..."/>(%%)
617 Il est possible de définir ses propres modes d'authentification (via des SecurityScheme) en ajoutant des propriétés au //jaxrs:server
618 //Exemple :
619
620
621
622 {{code language="none"}}
623 <bean id="openApiFeature" class="com.hardis.adelia.webservice.OpenApiFeatureExtended" lazy-init="true">
624 <!-- ... -->
625 </bean>
626
627 <jaxrs:server id="RestAdelia" address="/" transportId="http://cxf.apache.org/transports/http">
628 <jaxrs:features>
629 <ref bean="openApiFeature" />
630 </jaxrs:features>
631 <jaxrs:properties>  
632 <entry key="SwaggerSecurityDefinitions">
633 <map>
634 <entry key="jwt_Key">
635 <bean class="io.swagger.v3.oas.models.security.SecurityScheme" >
636 <property name="name" value="jwt_Key"/>
637 <property name="type">
638 <value type="io.swagger.v3.oas.models.security.SecurityScheme.Type">HTTP</value>
639 </property>
640 <property name="scheme" value="bearer"/>
641 <property name="bearerFormat" value="JWT"/>
642 </bean>
643 </entry>
644 <entry key="basic_Key">
645 <bean class="io.swagger.v3.oas.models.security.SecurityScheme" >
646 <property name="name" value="basic_Key"/>
647 <property name="type">
648 <value type="io.swagger.v3.oas.models.security.SecurityScheme.Type">HTTP</value>
649 </property>
650 <property name="scheme" value="basic"/>
651 </bean>
652 </entry>
653 </map>
654 </entry>  
655 </jaxrs:properties>
656 </jaxrs:server>
657 {{/code}}
658
659
660 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)**
661 Ajout d'annotations permettant à swagger-ui d'afficher la définition Adélia des champs alpha et numérique :**(%%)(%%)
662 //maxLength// donne la longeur maximale (longueur Adélia) d'un champ alphanumérique
663 //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.
664 **Mise en garde** : Swagger-UI n'affiche correctement que les entiers compris entre -9007199254740991 et 9007199254740991. Les entiers en dehors de cette plage ainsi que certains nombres décimaux peuvent faire l'objet d'un arrondi.
665
666
667 (((
668 = ((% style="color: rgb(255,0,0);" %)V14 PTF10(%%)) =
669 )))
670
671 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF010 intègre les librairies : (%%)(%%)
672 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.4.10
673 (%%)(%%)
674 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 2.2.19(%%)(%%)
675 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.ui 5.10.3(%%)(%%)
676 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)springframework : 5.3.31(%%)(%%)
677
678
679
680
681 (((
682 = ((% style="color: rgb(255,0,0);" %)V14 PTF11(%%)) =
683 )))
684
685 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF011 intègre les librairies : (%%)(%%)
686 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.5.8
687 (%%)(%%)
688 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 2.2.22(%%)(%%)
689 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.ui 5.17.14(%%)(%%)
690 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)springframework : 5.3.36(%%)(%%)
691
692
693
694
695 (((
696 = ((% style="color: rgb(255,0,0);" %)V14 PTF12(%%)) =
697 )))
698
699 (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)La version V14 PTF012 intègre les librairies : (%%)(%%)
700 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)CXF 3.5.10
701 (%%)(%%)
702 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.core 2.2.23(%%)(%%)
703 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)swagger.ui 5.18.2(%%)(%%)
704 * (% style="color: rgb(0,0,255);" %)(% style="color: rgb(0,0,0);" %)springframework : 5.3.39(%%)(%%)
705
706