Chapter 173. 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).
173.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>2.17.0.redhat-630xxx</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.DefaultCamelSwaggerServletNoteThis 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.xThe Swagger servlet is integrated with either Spring or the
servletListenercomponent:- Spring
org.apache.camel.component.swagger.spring.SpringRestSwaggerApiDeclarationServlet servletListenercomponentorg.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.
|
| 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.
|
| 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
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.
