Grouping APIs in Swagger

We develop and manage lot of APIs but when it comes to sharing apis to other teams, most used approach is to expose them using swagger.

But, listing so many APIs in a single page in swagger can create confusion for the consumer. And also, there are some critical APIs that might change our database state or some configuration and we might not want to expose them.

To solve this, we can group APIs in Swagger (using springdoc-openapi) so that only limited APIs are displayed in one group.

Let' see how to accomplish this using spring-boot and springdoc-openapi.

Include springdoc-openapi-ui in pom.xml



        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.4.0</version>
        </dependency>

Make a simple ToDoController with 6 APIs i.e 2 for user,1 for admin, 3 for ops



@RequestMapping("/todo")
@RestController
public class ToDoController {

  private final Map<Integer, String> todoMap = new HashMap<>(30);
  private final Random random = new Random();

  @GetMapping(value = "/user")
  @Operation(summary = "Get All ToDo List")
  public Map<Integer, String> getAllTodoList() {
    return todoMap;
  }

  @GetMapping(value = "/user/{todo_id}")
  @Operation(summary = "Get ToDo item for todo id")
  public String getTodo(@PathVariable("todo_id") Integer todoId) {
    return todoMap.get(todoId);
  }

  @PostMapping(value = "/admin")
  @Operation(summary = "Post new ToDo")
  public Integer postTodo(@RequestParam("todo") String todo) {
    int todoId = random.nextInt();
    todoMap.put(todoId, todo);
    return todoId;
  }

  @GetMapping(value = "/operation")
  @Operation(summary = "Get All ToDo List")
  public Map<Integer, String> getAllTodoListByOps() {
    return todoMap;
  }

  @GetMapping(value = "/operation/{todo_id}")
  @Operation(summary = "Get ToDo item for todo id")
  public String getTodoByOps(@PathVariable("todo_id") Integer todoId) {
    return todoMap.get(todoId);
  }

  @PostMapping(value = "/operation")
  @Operation(summary = "Post new ToDo")
  public Integer postTodoByOps(@RequestParam("todo") String todo) {
    int todoId = random.nextInt();
    todoMap.put(todoId, todo);
    return todoId;
  }
}

Create three GroupedOpenApi beans i.e for user,admin and ops



  @Bean
  GroupedOpenApi userApis() { // group all APIs with `user` in the path
    return GroupedOpenApi.builder().group("user").pathsToMatch("/**/user/**").build();
  }

  @Bean
  GroupedOpenApi adminApis() { // group all APIs with `admin` in the path
    return GroupedOpenApi.builder().group("admin").pathsToMatch("/**/admin/**").build();
  }

  @Bean
  GroupedOpenApi opsApis() { // group all APIs with `operation` in the path
    return GroupedOpenApi.builder().group("operation").pathsToMatch("/**/operation/**").build();
  }