Overview

Dependencies

Maven users need to add the following dependency to their pom.xml file to use this component:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-swagger</artifactId>
    <version>2.17.0.redhat-630177</version>
    <!-- Use the same version as your Camel core version -->
<dependency>

Selecting the Swagger servlet

Which servlet you use depends on the Camel version you use:

Camel 2.15.x

org.apache.camel.component.swagger.DefaultCamelSwaggerServlet

	Note
	This default servlet integrates with any environment, using JMX to discover the CamelContext(s) to use. It replaces both Camel 2.14.x servlets, which are deprecated from Camel 2.15 onwards.

Camel 2.14.x
The Swagger servlet is integrated with either Spring or the servletListener component:
- Spring
  org.apache.camel.component.swagger.spring.SpringRestSwaggerApiDeclarationServlet
- servletListener component
  org.apache.camel.component.swagger.servletlistener.ServletListenerRestSwaggerApiDelarationServlet

Servlet configuration parameters

All of the servlets support these options:

Parameter	Type	Description
api.contact	String	Specifies an email used for API-related correspondence
api.description	String	[Required] Provides a short description of the application
api.license	String	Specifies the name of the license used for the API
api.licenseUrl	String	Specifies the URL of the license used for the API
api.path	String	[Required] Specifies the location at which the API is available. Camel 2.15 +—Enter the relative path only: `host:port/context-path/api.path` At run time, camel-swagger calculates the absolute api path. Camel 2.14.x—Enter the absolute api path: `protocol://host:port/context-path/api.path`.
api.termsOfServiceUrl	String	Specifies the URL to the Terms of Service of the API
api.title	String	[Required] Specifies the title of the application
api.version	String	Specifies the version of the API. The default is `0.0.0`.
base.path	String	[Required] Specifies the location at which the REST services are available. Camel 2.15 +—Enter the relative path only: `host:port/context-path/base.path`. At run time, camel-swagger calculates the absolute base path. Camel 2.14.x—Enter the absolute base path: `protocol://host:port/context-path/base.path`.
cors	Boolean	Specifies whether to enable CORS. This parameter enables CORS for the API browser only. It does not enable access to the REST services. The default is `false`. Using the CorsFilter (see x) is recommended instead of using this parameter.
swagger.version	String	Specifies the version of the Swagger Specification. The default is `1.2`.

Using the CorsFilter

If you use the Swagger UI to view the REST API, you will likely need to enable support for CORS. When the Swagger UI is hosted and running on a different hostname/port than the REST APIs, it needs access to the REST resources across the origin (CORS). The CorsFilter adds the necessary HTTP headers to enable CORS.

For all requests, the CorsFilter sets these headers:

Access-Control-Allow-Origin = *
Access-Control-Allow-Methods = GET, HEAD, POST, PUT, DELETE, TRACE, OPTIONS, CONNECT, PATCH
Access-Control-Max-Age = 3600
Access-Control-Allow-Headers = Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers

QUESTION: How do you set up the CorsFilter in Camel 2.15? Or do you?

To use it, with WAR deployments, add org.apache.camel.component.swagger.RestSwaggerCorsFilter to your WEB-INF/web.xml file. For example:

<!-- Use CORs filter so people can use Swagger UI to browse and test the APIs -->
                    
<filter>
     <filter-name>RestSwaggerCorsFilter</filter-name
     <filter-class>org.apache.camel.component.swagger.RestSwaggerCorsFilter</filter-class>
</filter>
 
<filter-mapping>
     <filter-name>RestSwaggerCorsFilter</filter-name>
     <url-pattern>/api-docs/*</url-pattern>
     <url-pattern>/rest/*</url-pattern>
</filter-mapping>

	Note
	This example shows a very simple CORS filter. You may need to use a more sophisticated filter to set header values differently for a given client or to block certain clients, and so on.