Swagger Integration (REST)

// Currently this is not supported within Pricefx, but customer can support this on their implementation

We can incorporate the use of a Swagger service to create API documentation for any REST-defined routes and endpoints in a CamelContext file. To enable this option, we need to use the Camel REST DSL with the camel-swagger-java module (it is Java-based).

The camel-swagger-java module will then create a servlet that is integrated with the CamelContext and it will then extract the information from each REST endpoint to generate the API documentation in JSON or YAML format.

In Maven we can edit the POM file to add a dependency on the camel-swagger-java component:

<dependency>
   <groupId>org.apache.camel</groupId>
   <artifactId>camel-swagger-java</artifactId>
   <version>x.x.x</version>
   <!-- Specify the version of your camel-core module. -->
</dependency>

Enable Swagger

To enable the use of the Swagger API in the Camel REST DSL, we will need to invoke apiContextPath() to set the context path for the Swagger-generated API documentation:

public class UserRouteBuilder extends RouteBuilder {
    @Override
    public void configure() throws Exception {
        // Configure the Camel REST DSL to use the netty4-http component:
        restConfiguration().component("netty4-http").bindingMode(RestBindingMode.json)
            // Generate pretty print output:
            .dataFormatProperty("prettyPrint", "true")
            // Set the context path and port number that netty will use:
            .contextPath("/").port(8080)
            // Add the context path for the Swagger-generated API documentation:
            .apiContextPath("/api-doc")
                .apiProperty("api.title", "User API").apiProperty("api.version", "1.2.3")
                // Enable CORS:
                .apiProperty("cors", "true");

        // This user REST service handles only JSON files:
        rest("/user").description("User rest service")
            .consumes("application/json").produces("application/json")
            .get("/{id}").description("Find user by id").outType(User.class)
                .param().name("id").type(path).description("The id of the user to get").dataType("int").endParam()
                .to("bean:userService?method=getUser(${header.id})")
            .put().description("Updates or create a user").type(User.class)
                .param().name("body").type(body).description("The user to update or create").endParam()
                .to("bean:userService?method=updateUser")
            .get("/findAll").description("Find all users").outTypeList(User.class)
                .to("bean:userService?method=listUsers");
    }
}

Swagger Configuration Options

Option	Type	Description

Option	Type	Description
api.contact.email	String	Email address to be used for API-related correspondence
api.contact.name	String	Name of person to contacts
api.contact.url	String	URL for more information
apiContextIdListing	Boolean	If your application uses more than one `CamelContext` object, the default behavior is to list the REST endpoints in only the current `CamelContext`. If you want a list of the REST endpoints in each `CamelContext` that is running in the JVM that is running the REST service then set this option to true
apiContextIdPattern	String	Pattern that filters which CamelContext IDs appear in the context listing.
api.license.name	String	License name used for API
api.license.url	String	URL for license used for API
api.title	String	Title of application
api.version	String	Version of the API
base.path	String	Sets the path where the REST services are available. Specify a relative path
host	String	Set the name of the host that the Swagger service is running on.