Documents how to configure the swagger API to work properly.


Swagger is a REST API framework that allows for easy documenation of REST services via annotations and includes an application for allowing users to interact with your services through a simple web interface.

There are several parts to making the Swagger API work properly and they are documented here.

The code itself is annotated with Swagger annotations that make all of this work. Consider the "findConceptsForQuery" method of the Content REST service:

@Api(value = "/content", description = "Operations to retrieve RF2 content for a terminology.")
public class ContentServiceRest extends RootServiceRest {

  @ApiOperation(value = "Find concepts matching a search query.", notes = "Gets a list of search results that match the lucene query.", response = String.class)
  public SearchResultList findConceptsForQuery(
    @ApiParam(value = "Query, e.g. 'heart attack'", required = true) @PathParam("string") String searchString,
    @ApiParam(value = "Authorization token", required = true) @HeaderParam("Authorization") String authToken) {

The class itself has an @Api annotation that describes this overall service.  The method itself has an @ApiOperation that describes what this service call itself does.  Then, each parameter has an @ApiParam annotation that describes the purpose of that parameter and whether it is required.  An attempt was made to provide example values that in a dev deployment of the system produce real values.


There are two minor nits with the current configuration to be aware of.

  1. When entering the URL for Swagger UI, you have to include "index.html" in the URL (e.g. http://localhost:8080/mapping-rest/index.html for a dev deployment).
  2. When configuring "base.url" you have to use a fully qualified base url. Various efforts to configure it with a relative URL (e.g. just the context path of the application) allow Swagger UI to work, but interactively trying to call the services does not work.