{SWAGGER}

Il est possible de paramétrer Swagger via le fichier de configuration Spring "/WEB-INF/beans.xml" en déclarant :

un bean faisant référence à la classe org.apache.cxf.jaxrs.swagger.Swagger2Feature
Exemple :

<bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature" lazy-init="true">
      <property name="basePath" value="/jaxrs/ws"/>
      <property name="resourcePackage" value="hardis.jaxrs"/>
      <property name="contact" value="hotline.adelia@hardis.fr" />
      <property name="title" value="REST Services List" />
      <property name="description" value="REST services documentation" />
      <property name="version" value="2.1" />
      <property name="termsOfServiceUrl" value="http://www.hardis-group.com" />
   </bean>

Détails

Name	Description	Default
basePath	the context root path⁺	null
contact	the contact information+	"users@cxf.apache.org"
description	the description+	"The Application"
filterClass	a security filter+	null
host	the host and port+	null
ignoreRoutes	excludes specific paths when scanning all resources (see scanAllResources)++	null
license	the license+	"Apache 2.0 License"
licenceUrl	the license URL+	"http://www.apache.org/licenses/LICENSE-2.0.html"
prettyPrint	when generating swagger.json, pretty-print the json document+	false
resourcePackage	a list of comma separated package names where resources must be scanned+	a list of service classes configured at the endpoint
runAsFilter	runs the feature as a filter	false
scan	generates the swagger documentation+	true
scanAllResources	scans all resources including non-annotated JAX-RS resources++	false
schemes	the protocol schemes+	null
termsOfServiceUrl	the terms of service URL+	null
title	the title+	"Sample REST Application"
version	the version+	"1.0.0"

Un bean faisant référence à la classe com.hardis.adelia.webservice.SwaggJaxbInit

Cette classe permet de modifier les propriétés utile à la sérialisation/désérialisation du flux Swagger/JSON (s'appuie sur fasterXML/Jackson).

Exemple :

<bean id="SwaggJaxbInit" class="com.hardis.adelia.webservice.SwaggJaxbInit" init-method="init" >
    <property name="jaxbMapper" value="true"/>
    <property name="serializeWRAP_ROOT_VALUE" value="false"/>
    <property name="serializeWRITE_DATES_AS_TIMESTAMPS" value="true"/>
    <property name="serializeWRITE_DATE_KEYS_AS_TIMESTAMPS" value="false"/>
    <property name="serializeWRITE_CHAR_ARRAYS_AS_JSON_ARRAYS" value="false"/>
    <property name="serializeWRITE_EMPTY_JSON_ARRAYS" value="true"/>
    <property name="serializeWRITE_SINGLE_ELEM_ARRAYS_UNWRAPPED" value="false"/>
    <property name="deserializeUSE_JAVA_ARRAY_FOR_JSON_ARRAY" value="false"/>
    <property name="deserializeACCEPT_SINGLE_VALUE_AS_ARRAY" value="false"/>
    <property name="deserializeUNWRAP_ROOT_VALUE" value="false"/>
    <property name="deserializeUNWRAP_SINGLE_VALUE_ARRAYS" value="false"/>
    <property name="deserializeFAIL_ON_IGNORED_PROPERTIES" value="false"/>
    <property name="deserializeFAIL_ON_UNKNOWN_PROPERTIES" value="true"/>    
  </bean>

Les détails sur les propriétés se trouvent :
https://github.com/FasterXML/jackson-databind/wiki/Serialization-features
https://github.com/FasterXML/jackson-databind/wiki/Deserialization-Feature

(Adélia V13 PTF9)

La version V13 PTF09 intègre les librairies :

CXF 3.1.15
swagger.core 1.5.18
swagger.ui 3.13.0

Par défaut tous les éléments de swagger-ui sont intégrés dans le .jar swagger-ui-3.13.0.jar.
La présence dans le bean Swagger2Feature (Cf. beans.xml) de la propriété 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.

L'accès à swagger-ui est disponible via l'URL : http(s)://<host>:<port>/<RootContext>/<CXFServlet>/services
Exemple :

en cliquant sur le lien en face de Swagger.

Accès à une ressource sécurisée par un jeton JWT
Pour que swagger-ui offre la possibilité de passer un jeton JWT via le header HTTP Authorization, il faut :

A. Indiquer à swagger-ui qu'il doit afficher le bouton [Authorize] / cadenas. Pour cela,

soit la propriété resourcePackage du bean Swagger2Feature possède, en tête de liste, le package com.hardis.adelia.webservice
Exemple :

<bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature" lazy-init="true">   
      <property name="basePath" value="/domsvx/ws"/>    
      <property name="resourcePackage" value="com.hardis.adelia.webservice,hardis.fr" />
<!-- ... -->
</bean>

soit l'élément <jaxrs:server> déclare une propriété SwaggerSecurityDefinitions de type ApiKeyAuthDefinition.
Exemple :

<jaxrs:server id="RestAdelia" address="/" transportId="http://cxf.apache.org/transports/http">              
	<jaxrs:features>
    	<ref bean="swagger2Feature" />
	</jaxrs:features>          
    <jaxrs:properties>
		<entry key="SwaggerSecurityDefinitions">
        	<map>
            	<entry key="jwt_Key">        
                	<bean class="io.swagger.models.auth.ApiKeyAuthDefinition">  
                    	<property name="name" value="Authorization"/>
						<property name="in">
                        	<value type="io.swagger.models.auth.In">HEADER</value>
						</property>  
                  	</bean>
               	</entry>
           	</map>
         </entry>
	</jaxrs:properties>
</jaxrs:server>

B. Cliquer sur le bouton [Authorize] ou sur le cadenas propre à une API et renseigner le champ [Value:] avec la valeur du jeton précédée de "JWT "

Cliquer ensuite sur le bouton [Authorize].

Services web RESt - Swagger

(Adélia V13 PTF9)