loading...
Cover image for Grouping APIs in Swagger

Grouping APIs in Swagger

s2agrahari profile image Suraj ・3 min read

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.

        <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.

Let's see the three groups created in Swagger

  • User Group

  • Operation Group

  • Admin Group

Complete Code 👇

GitHub logo 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.

Read more: 👇

Global Header in Swagger-Ui using springfox

Posted on by:

s2agrahari profile

Suraj

@s2agrahari

Happy to Develop

Discussion

pic
Editor guide
 

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?