Integrating swagger with camel cxfrs is two step process:
1) Creating Json file (based on Swagger annotations)
2) Using Swagger UI for exposing your rest services.
1) Creating Json file (based on Swagger annotations)
------------------------------------------------------A) pom.xml -- describing only swagger related stuff
<!-- swagger dependecny ->
<dependency>
<groupId>com.wordnik</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.3.7</version>
</dependency>
<!-- Cross Origin dependency --> <!--This is required so that you can make call to your application from swagger ui -->
<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-security-cors</artifactId>
<version>3.0.0</version>
</dependency>
<!--Swagger plugin--> <-- Change the setting as per your requirment -->
<!--This pluing is used to generate Json file -->
<plugin>
<groupId>com.github.kongchen</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>2.3</version>
<configuration>
<apiSources>
<apiSource>
<!--Required parameters BEGIN-->
<locations>com.rest.resources;com.rest.model;</locations>
<apiVersion>1.0</apiVersion>
<basePath>rest/v1</basePath>
<!--Required parameters END-->
<!--Optional parameters BEGIN-->
<!---General parameters BEGIN-->
<apiInfo>
<title>REST API Docs</title>
<description>REST api documentation</description>
<termsOfServiceUrl>http://www.github.com/kongchen/swagger-maven-plugin</termsOfServiceUrl>
<contact></contact>
<license>Apache 2.0</license>
<licenseUrl>http://www.apache.org/licenses/LICENSE-2.0.html</licenseUrl>
</apiInfo>
<!--<overridingModels>/swagger-overriding-models.json</overridingModels>-->
<swaggerInternalFilter>com.wordnik.swagger.config.DefaultSpecFilter</swaggerInternalFilter>
<!--General parameters END-->
<!---Document generation parameters BEGIN-->
<!-- <outputTemplate>
strapdown.html.mustache
</outputTemplate>
<mustacheFileRoot>${basedir}/src/main/resources/</mustacheFileRoot>
<outputPath>${basedir}/generated/document.html</outputPath>
-->
<!---Document generation parameters END-->
<!---Swagger JSON parameters BEGIN-->
<swaggerDirectory>target/classes/swagger</swaggerDirectory>
<swaggerUIDocBasePath>http://localhost:8083/swagger</swaggerUIDocBasePath>
<useOutputFlatStructure>false</useOutputFlatStructure>
<!---Swagger JSON parameters END-->
<!--Optional parameters END-->
</apiSource>
</apiSources>
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
---------------------------------------------------------
B) Anotating your class with Swagger annotations.
Check the below link for detail.
annotate-your-resources
annotate-your-methods
annotate-your-models
C) Creating your Camel Rest end point Server:
cxf-server.xml
--------------------
<cxf:rsServer id="camelRESTServer" address="${api.base.path}">
<cxf:serviceBeans>
<ref bean="camelResource"/> <!-- some resouce ->
</cxf:serviceBeans>
<cxf:providers>
<ref bean="jacksonJaxbJsonProvider"/>
<ref bean="cros"/> <!-- this is important else it will cause issue when calling your rest end point from swagger ui -->
</cxf:providers>
</cxf:rsServer>
<bean id="jacksonJaxbJsonProvider" class="com.fasterxml.jackson.jaxrs.json.JacksonJaxbJsonProvider"/>
<bean id="cros" class="org.apache.cxf.rs.security.cors.CrossOriginResourceSharingFilter"/>
-------------------
Same configuration in Java:
CxfServletConfiguration.java
--------------------
@Bean(name = "camelRESTServer")
JAXRSServerFactoryBean camelRESTServer() {
SpringJAXRSServerFactoryBean sf = new SpringJAXRSServerFactoryBean();
sf.setServiceBean(Arrays.asList(camelResources)); //some resource
sf.setAddress("api.base.path");
JacksonJaxbJsonProvider jacksonJaxbJsonProvider= new JacksonJaxbJsonProvider();
jacksonJaxbJsonProvider.setMapper(new ObjectMapper());
sf.setProviders(Arrays.asList(jacksonJaxbJsonProvider,
new CrossOriginResourceSharingFilter())); /*this is important else it will cause issue when calling your rest end point from swagger ui */
return sf;
}
--------------------
D) Define your Camel route to cater the rest request.
see : cxfrs
F) Creating a servlet which serve the JSON file created by the pluging which we have described above. This servlet will be called from Swagger UI.
------configuration ----
@Bean
public ServletRegistrationBean swaggerServletRegistrationBean() {
Swagger swaggerServlet = new Swagger();
ServletRegistrationBean swaggerServletRegistrationBean = new ServletRegistrationBean(swaggerServlet, "/swagger/*");
return swaggerServletRegistrationBean;
}
---------------------
Swagger.java
public class Swagger extends HttpServlet {
public void doGet(HttpServletRequest request, HttpServletResponse response)throws ServletException, IOException {
response.setContentType("application/json");
//allow Swagger on other servers to read JSON
response.addHeader("Access-Control-Allow-Origin", "*");
//get end of the address browser asks for
String jsonFile=request.getRequestURI();
//lets us point at just /swagger instead of service.json, which is prettier
if (request.getRequestURI().equals("/swagger"))
{
jsonFile = jsonFile +"/service.json";
}
//gets file location of generated JSON
URL resource = getClass().getResource(jsonFile);
//populates a String with JSON
String fileContent = FileUtils.getFileContent(resource.toString().substring(6));
//prints String to page served
PrintWriter out = response.getWriter();
out.print(fileContent);
}
}
-------------------------------------------------
That is end of step 1. Build your application and Run it.
2) Using Swagger UI for exposing your rest services.
Download the Swagger UI from swagger-uiTo launch the Swagger UI you can copy the dist folder and put it into tomcat webapps folder.
Rename dist to swagger.
Run your tomcat. and launch http://localhost:<port>/swagger
Above step will launch swagger ui, now give the url which will be served by your application Swagger servlet.
At this point your should be able to see your exposed REST services.
Nice blog
ReplyDelete