Grouping APIs in Swagger
Tags: swagger, springdoc, openapi, group
Published: 2020-06-09 20:16:18

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](https://swagger.io/docs/specification/2-0/what-is-swagger/).

But, listing so many APIs in a single page in [swagger](https://swagger.io/docs/specification/2-0/what-is-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](https://swagger.io/docs/specification/2-0/what-is-swagger/) (using [springdoc-openapi](https://springdoc.org/)) so that only limited APIs are displayed in one group.

![](https://github.com/s2agrahari/img-dump/blob/master/springdocopenapi_grouped_swagger_options.png?raw=true)

Let' see how to accomplish this using spring-boot and [springdoc-openapi](https://springdoc.org/).

* Include [springdoc-openapi-ui](https://springdoc.org/) in `pom.xml`

```yml
        <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

```java
@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

```java
  @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](localhost:8080/swagger-ui.html)


Let's see the three groups created in [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/)

* User Group

![](https://github.com/s2agrahari/img-dump/blob/master/springdocopenapi_grouped_swagger_user_goup.png?raw=true)

* Operation Group

![](https://github.com/s2agrahari/img-dump/blob/master/springdocopenapi_grouped_swagger_operation_group.png?raw=true)

* Admin Group

![](https://github.com/s2agrahari/img-dump/blob/master/springdocopenapi_grouped_swagger_admin_goup.png?raw=true)

Complete Code :point_down: 
{% github https://github.com/s2agrahari/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: :point_down:

[Global Header in Swagger-Ui using springfox](
https://dev.to/s2agrahari/global-header-in-swagger-ui-spring-boot-5188)