Spring 5 中函式式web開發中的swagger文件

山不在高水不在深發表於2021-10-27
Spring函式WebSwagger

Spring 5 中一個非常重要的更新就是增加了響應式web開發WebFlux，並且推薦使用函式式風格（RouterFunction和 HandlerFunction）來開發WebFlux。對於之前主流的MVC開發模式，Spring也順道給它提供了和WebFlux函式式開發幾乎一致的方式（見上文《Spring 5 MVC 中的 Router Function 使用》）。這樣，響應式WebFlux和非響應式MVC都可以通過Controller來實現，也都可以通過RouterFunction來實現。

但是Spring推薦使用函式式方式；而且聽說在所有場景也推薦使用WebFlux，後續有可能廢棄掉非響應式MVC

對於通過Controller來實現的介面，swagger可以直接掃描處理。使用了RouterFunction的怎麼辦呢？這篇文章我們來看一下如果通過springdoc這個專案來實現函式式介面的文件生成。

pom依賴

假設你使用的是maven。如果使用gradle我估計也差不多

要使用springdoc-openapi，需要新增它的依賴。一般需要兩個，第一個是基礎公共依賴：

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

另一個根據物件不同需要引入的也不同。我們這裡先處理非響應式MVC的介面，需要依賴

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-webmvc-core</artifactId>
    <version>1.5.9</version>
</dependency>

依賴的版本號可以自己去查一下最新的

RouterOperation

接下來需要去RouterFunction上面定義swagger的顯示資訊，在controller中使用的註解是io.swagger.v3.oas.annotations.Operation（如果是版本2使用的註解是io.swagger.annotations.ApiOperation），現在需要使用org.springdoc.core.annotations.RouterOperation。以《Spring 5 MVC 中的 Router Function 使用》中的介面為例，需要這樣寫

@Configuration
public class RoutingConfig {

    @Bean
    @RouterOperations({
            @RouterOperation(
                    path = "/model/building/{entId}/stations",
                    beanClass = ModelBuildingHandler.class,
                    beanMethod = "getStations",
                    method = RequestMethod.GET,
                    operation = @Operation(
                            operationId = "getStations",
                            parameters = @Parameter(
                                    name = "entId",
                                    in = ParameterIn.PATH,
                                    required = true,
                                    description = "企業ID"
                            )
                    )
            )
    })
    public RouterFunction<ServerResponse> getModelBuildingRouters(ModelBuildingHandler modelBuildingHandler) {
        return RouterFunctions.nest(path("/model/building"),
                RouterFunctions.route(GET("/{entId}/stations"), modelBuildingHandler::getStations)
                        .andRoute(GET("/{stationId}/device-types"), modelBuildingHandler::getDeviceTypes)
        );
    }
}

不同於Controller中的介面會被自動發現，這裡雖然有兩個方法但是我們只定義了一個RouterOperation操作，會導致看不到第二個方法。

我們修改一下application.properties就能看到效果了：

springdoc.packagesToScan=要掃描的包
springdoc.pathsToMatch=/**

注意springdoc.packagesToScan這裡，需要寫一個包含了RouterFunction和 HandlerFunction實現的包。我當時只寫了RouterFunction所在的包，一直不成功

再響應增加一個RouterOperation即可：

@RouterOperations({
        @RouterOperation(
                path = "/model/building/{entId}/stations",
                beanClass = ModelBuildingHandler.class,
                beanMethod = "getStations",
                method = RequestMethod.GET,
                operation = @Operation(
                        operationId = "getStations",
                        parameters = @Parameter(
                                name = "entId",
                                in = ParameterIn.PATH,
                                required = true,
                                description = "企業ID"
                        )
                )
        ),
        @RouterOperation( // 這裡我省略了一些屬性配置
                path = "/model/building/{stationId}/device-types",
                beanClass = ModelBuildingHandler.class,
                beanMethod = "getDeviceTypes"
        )
})

RequestBody

上面講的都是GET的請求，如果需要設定請求體格式怎麼辦呢？

在RouterFunction中增加一個POST請求（下面最後一個url）：

public RouterFunction<ServerResponse> getModelBuildingRouters(ModelBuildingHandler modelBuildingHandler) {
  return RouterFunctions.nest(
          path("/model/building"),
          RouterFunctions.route(GET("/{entId}/stations"), modelBuildingHandler::getStations)
                  .andRoute(GET("/{stationId}/device-types"), modelBuildingHandler::getDeviceTypes)
                  .andRoute(POST("/devices/points/real-time-data"), modelBuildingHandler::getRealTimeData)
  );
}

它對應的RouterOperation如下：

@RouterOperation(
        path = "/model/building/devices/points/real-time-data",
        beanClass = ModelBuildingHandler.class,
        beanMethod = "getRealTimeData",
        operation = @Operation(
                operationId = "getRealTimeData",
                requestBody = @RequestBody(
                        required = true,
                        description = "請求體",
                        content = @Content(
                                schema = @Schema(implementation = RealTimeDataQueryVO.class)
                        )
                )
        )
)

要在Handler中拿到請求引數，使用body方法：RealTimeDataQueryVO queryVo = req.body(RealTimeDataQueryVO.class);

public ServerResponse getRealTimeData(ServerRequest req) {
    RealTimeDataQueryVO queryVo;
    try {
        queryVo = req.body(RealTimeDataQueryVO.class);
        log.info("請求引數{}", queryVo);
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
    RealTimeDataResultBO resultBo = modelBuildingService.getRealTimeData(transferRealTimeDataQueryParam(queryVo));
    return body(RdfaResult.success(transferRealTimeDataResult(resultBo)));
}

上面就是如何在函式式MVC程式設計中使用swagger。可以看到比較繁瑣，3行程式碼對應了差不多30行swagger配置。

從swagger v2 遷移

如果之前的專案使用的是springfox之類的swagger版本2，需要將其依賴移除，並修改類上的註解。

如何修改可以參考 https://springdoc.org/#migrating-from-springfox

主要的變更點如下圖：

Swagger配置

這一步是可選的，幾乎沒什麼必要。

可以像之前一樣定義文件的歸屬、協議、版本等等：

@Configuration
public class DocConfig {
    @Bean
    public OpenAPI springShopOpenApi() {
        return new OpenAPI()
                .info(new Info().title("測試 API")
                        .description("樣例程式")
                        .version("v0.0.1")
                        .license(new License()
                                .name("Apache 2.0我的協議")
                                .url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("外部文件連結")
                        .url("https://springshop.wiki.github.org/docs"));
    }
}

WebFlux 中的文件

如果專案不是mvc的而是webFlux的，相應的Maven依賴改成下面的即可：

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

其他類似。

相關文章