Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 150. Swagger

Abstract

The Swagger component enables users to create API docs for any Rest-defined routes and endpoints in a CamelContext file. The Swagger component creates a servlet integrated with the CamelContext that pulls information from each Rest endpoint to generate the API docs (JSON file).

150.1. Overview

Available as of Camel 2.14
The Rest DSL can be integrated with the camel-swagger component, which is used for exposing REST services and their APIs using Swagger.

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>x.x.x</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:
ParameterTypeDescription
api.contact StringSpecifies an email used for API-related correspondence
api.description String[Required] Provides a short description of the application
api.license StringSpecifies the name of the license used for the API
api.licenseUrl StringSpecifies 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 StringSpecifies the URL to the Terms of Service of the API
api.title String[Required] Specifies the title of the application
api.version StringSpecifies 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 StringSpecifies 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
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.