Multiple Swagger Groups

Swagger Group

Swagger allows you to categorize resources under different groups for a project with multiple controllers.

Instead of showing all the different REST endpoints in one page, the menagerie endpoints are categorized in two different groups based on their taxonomy class, i.e., animal or bird. Each of the groups has a different api-docs URL and the groups are shown in separate Swagger UI pages.

Single Group

Here is how the Swagger UI looks when all the REST controllers are grouped under group named menagerie.

Multiple Groups

In the case of multiple groups, the menagerie animal and bird controllers are grouped under animal and bird groups respectively.

Here is the Swagger UI for the animal group. The animal api-docs is accessed at, http://<host>:<port>/v2/api-docs?group=animal

The Swagger UI for the bird group is shown below. The bird api-docs is accessed at, http://<host>:<port>/v2/api-docs?group=bird

Multiple Dockets

Springfox provides Docket class to configure the REST controllers. Docket acts as the primary interface into the swagger-springmvc framework. In the menagerie example, animal and bird controllers are kept in separate packages and each of the package has a separate Docket bean. The exactPackage method picks up all the controller classes within a given package. The Docket beans are declared in the SwaggerConfiguration class.

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket animalsApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("animal")
                .select()
                .apis(exactPackage(
                        "com.basaki.example.menagerie.controller.animal"))

                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo("Animal APIs",
                        "Exploring Swagger UI Features"));
    }

    @Bean
    public Docket birdsApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("bird")
                .select()
                .apis(exactPackage(
                        "com.basaki.example.menagerie.controller.bird"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo("Bird APIs",
                        "Exploring Swagger UI Features"));
    }

    /**
     * Creates an object containing API information including author name,
     * email, version, license, etc.
     *
     * @param title       API title
     * @param description API description
     * @return API information
     */
    private ApiInfo apiInfo(String title, String description) {
        Contact contact = new Contact("Indra Basak", "",
                "[email protected]");
        return new ApiInfo(title, description, "1.0", "terms of controller url",
                contact, "license", "license url");
    }

    private static Predicate<RequestHandler> exactPackage(final String pkg) {
        return input -> input.declaringClass().getPackage().getName().equals(
                pkg);
    }
}