4.5. Swagger Integration
Overview
Integrated with the REST DSL, the
camel-swagger component enables users to create API docs for any REST-defined routes and endpoints in a CamelContext file. The camel-swagger component creates a servlet integrated with the CamelContext that pulls the information from each REST endpoint to generate the API docs (JSON file).
If using Maven, you need to add the
camel-swagger component to your pom.xml file:
<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-swagger</artifactId> <version>x.x.x</version> <!-- Use the same version as your Camel core version --> </dependency>
Configuring the camelContext
To enable Swagger, add to the CamelContext file:
- The
serviceelement, which exposes the camel-swagger servlet and initializes its parameters.In the service element, add the servlet (org.apache.camel.component.swagger.DefaultCamelSwaggerServlet) and theservice-propertiesthat configure the servlet's parameters.For details on servlet parameters, see Swagger in the Apache Camel Component Reference Guide. - Configure the REST implementationDefine the REST service within the
camelContextelement using therestConfigurationandrestelements.For details on configuring REST services in the CamelContext, see Section 4.2, “Defining Services with REST DSL”.
For OSGi deployments, you need to configure the servlet options and REST configuration in the
blueprint.xml file; for example:
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.osgi.org/xmlns/blueprint/v1.0.0
http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
http://camel.apache.org/schema/blueprint
http://camel.apache.org/schema/blueprint/camel-blueprint.xsd">
<service interface="javax.servlet.http.HttpServlet">
<service-properties>
<entry key="alias" value="/api-docs/*"/>
<entry key="init-prefix" value="init."/>
<entry key="init.base.path" value="//localhost:8080/"/>
<entry key="init.api.path" value="//localhost:8181/api-docs"/>
<entry key="init.api.title" value="Camel Rest Example API"/>
<entry key="init.api.version" value="1.2"/>
<entry key="init.api.description"
value="Camel Rest Example with Swagger that provides an User REST service"/>
</service-properties>
<bean class="org.apache.camel.component.swagger.DefaultCamelSwaggerServlet" />
</service>
<camelContext id="log-example-context"
xmlns="http://camel.apache.org/schema/blueprint">
<restConfiguration component="jetty" port="8080"/>
<rest path="/say">
<get uri="/hello">
<to uri="direct:hello"/>
</get>
<get uri="/bye" consumes="application/json">
<to uri="direct:bye"/>
</get>
<post uri="/bye">
<to uri="mock:update"/>
</post>
</rest>
<route id="rte1-log-example">
<from uri="direct:hello"/>
<transform>
<constant>Hello World</constant>
</transform>
</route>
<route id="rte2-log-example">
<from uri="direct:bye"/>
<transform>
<constant>Bye World</constant>
</transform>
</route>
</camelContext>
</blueprint>
The following parameters are used in the above example as described here:
-
service - The
serviceelement exposes the camel swagger servlet (<bean class="org.apache.camel.component.swagger.DefaultCamelSwaggerServlet"/>) and initializes several servlet properties. -
alias - The
aliasproperty binds the camel swagger servlet to/api-docs/*. -
init-prefix - The
init-prefixproperty sets the prefix for all camel swagger servlet properties toinit.. This is analogous to usinginit-paramelements in theweb.xmlconfiguration for WAR implementations (see chapter "Swagger" in "Apache Camel Component Reference"). -
restConfiguration - In the
camelContextelement, therestConfigurationelement specifies the REST implementation to use. In this case, it is Jetty web servlet on port 8080. -
rest - In the
camelContextelement, therestelement defines a REST service and provides the base path (/say) to it. In this case, the service consists of two REST endpoints,helloandbye, which are routed to their corresponding camel endpoints defined in therouteelements.
