Grouping APIs in Swagger

#swagger #springdoc #openapi #group

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();
  }

Note -> pathsToMatch() in above code accepts a regular expression of the API path which we are grouping.

Now, run spring-boot application and open localhost:8080/swagger-ui.html

Let's see the three groups created in Swagger

User Group

Operation Group

Admin Group

Complete Code 👇

s2agrahari / grouping-in-swagger-springdoc-openapi

grouping-in-swagger-springdoc-openapi

🍻 If you enjoyed this story, please click the ❤️ button and share it to help others find it! Feel free to leave a comment below.

Top comments (3)

nivekalara237 • Oct 22 '20

Great article thank. But I have some problem to do my own
The problem is that I have Microservices separated and I want to groups their in my gateway. Do have any idea to do it?