如何使用 SpringDoc openAPI 为两个模块公开单个 swagger-ui

Question

我正在尝试公开一个 swagger-ui，它记录了在两个不同模块中公开的控制器的 api。

控制器位于不同的模块中，因为我需要它们位于单独的容器中

这是我的项目结构的简化视图：

.
├── rest1
│   └── java.com.foo.bar
│       └── controller
│           └── impl
│               ├── UserController.java
├── rest2
│   └── java.com.foo.bar
│       └── controller
│           └── impl
│               ├── ActionController.java
├── rest-commons
│   └── java.com.foo.bar
│       └── controller
│           └── api
│               ├── UserControllerSpec.java
│               ├── ActionControllerSpec.java

ControllerSpec 类包含所有 swagger 注释，而实际的 Controller 类仅具有 @RestController 注释。

// UserControllerSpec.java
@RequestMapping("V1")
@Tag(name = "Users")
public interface UserControllerSpec {

  @Operation(summary = "Get Users")
  @ApiResponses({
    @ApiResponse(responseCode = "200"),
  })
  @GetMapping(value = "/users")
  ResponseEntity<UserResponsePayload> getUsers(HttpServletRequest request);
}


// ActionControllerSpec.java
@RequestMapping("V1")
@Tag(name = "Actions")
public interface ActionControllerSpec {

  @Operation(summary = "Get Actions")
  @ApiResponses({
    @ApiResponse(responseCode = "200"),
  })
  @GetMapping(value = "/actions")
  ResponseEntity<ActionResponsePayload> getActions(HttpServletRequest request);
}


// UserController.java
@RestController
public class UserController implements UserControllerSpec {

  @Override
  public ResponseEntity<UserResponsePayload> getUsers(HttpServletRequest request) {
    return null;
  }
}


// ActionController.java
@RestController
public class ActionController implements ActionControllerSpec {
  
  @Override
  public ResponseEntity<ActionResponsePayload> getActions(HttpServletRequest request) {
    return null;
  }
}

我的最终目标是让rest1服务器公开一个包含两个api规范的swagger-ui。

我尝试手动扫描 Spec 类，如下所示，但没有成功：

public class OpenAPIConfig {
  static {
    SpringDocUtils.getConfig().addRestControllers(UserControllerSpec.class);
  }

仅当提供的类用 @RestController 或 @Controller 注释时才有效。

Answer 1

GroupedOpenApi

可能是一个解决方案。请参阅https://springdoc.org/faq.html。

根据您提供的示例：

@Configuration
public class OpenApiConfig {

    @Bean
    public GroupedOpenApi apiGroup() {
        String[] packages = { "java.com.foo.bar.controller.api" };
        return GroupedOpenApi.builder().group("api").packagesToScan(packages)
                .build();
    }

}