How can I document a RestController of a Spring Boot webapp with Swagger?

Question

I would like to add the following REST controller to an existing Spring Boot webapp and document it using Swagger:

@RestController
@Api(description="Querying concepts")
public class KnowledgeModelController {
    private ConceptService conceptService;
    @Autowired
    public KnowledgeModelController(ConceptService conceptService) {
        this.conceptService = conceptService;
    }
    @ApiOperation(value = "Returns a concept identified by its URI, optionally restricted by its branch", response = ConceptService.Concept.class)
    @RequestMapping(value = "/concept", method = RequestMethod.GET)
    public ConceptService.Concept getConcept(Optional<String> branch, String uri) {
        return conceptService.getConcept(branch, uri);
    }
}

However, simply adding springfox-swagger2 and springfox-swagger-ui dependencies does not work out of the box.

Although both the RestController (and thus the documentation endpoint /v2/api-docs that springfox generates for it) and swagger-ui.html are mapped under the root path /, swagger-ui.html does not find /v2/api-docs. My explanation is that swagger-ui.html navigates to ../v2/api-docs, but .. does not exist when in /.

The problem could obviously solved by moving the entire webapp to a non-root context path. However, I cannot go that route since clients already know and use certain of its endpoints.

How can springfox and swagger be made to work in this scenario?

Answer 1

The solution I found implements the following strategy:

1. map the new RestController to a non-root context path /restpath. This will also make springfox to expose its endpoint at /restpath/v2/api-docs.
2. let all Swagger resources appear under /restpath instead at /, so that navigation from /restpath/swagger-ui.html to /restpath/v2/api-docs works.

To do the first I simply add a @RequestMapping("/restpath") annotation to the RestController class.

The second can be achieved by adding the following WebMvcConfigurerAdapter to the webapp:

@Configuration
public class MvcConfig extends WebMvcConfigurerAdapter {
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        super.addViewControllers(registry);
        registry.addRedirectViewController("/restpath/v2/api-docs", "/v2/api-docs").setKeepQueryParams(true);
        registry.addRedirectViewController("/restpath/swagger-resources/configuration/ui","/swagger-resources/configuration/ui");
        registry.addRedirectViewController("/restpath/swagger-resources/configuration/security","/swagger-resources/configuration/security");
        registry.addRedirectViewController("/restpath/swagger-resources", "/swagger-resources");
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/restpath/**").addResourceLocations("classpath:/META-INF/resources/");
    }
}

Now at http://localhost:8080/restpath/swagger-ui.html you should be able to see the /restpath/concept endpoint documented.