2

我正在使用他们的Contract APIs构建一个带有http4k 框架的微服务。我可以轻松地在例如上公开 swagger API 描述 JSON。和/swagger.json

fun app(): HttpHandler = "/" bind contract {
    renderer = OpenApi3(ApiInfo("GoOut Locations API", "1.0"), Jackson)
    descriptionPath = "/swagger.json"
    routes += ...
}

有没有一种简单的方法来公开招摇 UI，以便 1）我可以指定它可用的路径。（例如。/swagger-ui） 2) UI 将被预先配置为从descriptionPath上面指定的获取描述 JSON。

一个理想的 API 看起来像

fun app(): HttpHandler = "/" bind contract {
    renderer = OpenApi3(ApiInfo("GoOut Locations API", "1.0"), Jackson)
    descriptionPath = "/swagger.json"
    uiPath = "/swagger-ui"
    routes += ...
}
4

3 回答 3

2

经过一番搜索后，我结合了Web Jars和 http4k 的静态路由来实现这一点。

文档的潜在查看者必须简单地访问/docs他被重定向到的/docs/index.html?url=<path to Api description>路径

  • index.html是从 web jar 提供的静态 Swagger UI 入口点。
  • url查询参数告诉 swagger UI 从哪里获取 OpenApi 描述。

从 DX 的角度来看，我们有一个简单的 http4k 应用程序：

// path the OpenApi description will be exposed on
private const val API_DESCRIPTION_PATH = "/swagger.json"

fun app(): HttpHandler {
    val api = contract {
        renderer = OpenApi3(ApiInfo("Your API summary", "1.0"), Jackson)
        descriptionPath = API_DESCRIPTION_PATH
        // the actual API routes
        routes += ... 
    }

     return routes(
         // the docs routes are not considered part of the API so we define them outside of the contract
         swaggerUi(API_DESCRIPTION_PATH),
         api
     )
}

处理swaggerUi程序实现如下

/**
 * Exposes Swagger UI with /docs path as its entry point.
 * @param descriptionPath absolute path to API description JSON. The UI will be configured to fetch it after load.
 */
fun swaggerUi(descriptionPath: String): RoutingHttpHandler = routes(
    "docs" bind Method.GET to {
        Response(Status.FOUND).header("Location", "/docs/index.html?url=$descriptionPath")
    },
    // For some reason the static handler does not work without "/" path prefix.
    "/docs" bind static(Classpath("META-INF/resources/webjars/swagger-ui/3.25.2"))
)

我们还必须包含swagger-ui webjar作为我们的依赖项。这是一个 Gradle 指令：

implementation 'org.webjars:swagger-ui:3.25.2'

有关 Maven（以及更多）指令，请参阅 webjars 网站。

请注意，swaggerUi处理程序假定它绑定到/整个服务的根路径。但是，这很容易解决。

于 2020-05-13T11:08:15.993 回答
1

http4k 不附带 OpenApi UI 的版本。您可以通过以下方式轻松发布 UI 版本：

  1. 将 OpenApi UI 解压到 src/main/resources/public 文件夹中
  2. 使用static路由块来服务资源。这里有一个例子：https ://github.com/http4k/http4k-by-example/blob/22dcc9a83c497253c29830d5bc981afa5fbbe4ff/src/main/kotlin/verysecuresystems/SecuritySystem.kt#L61
于 2020-05-12T15:41:40.307 回答
1

使用 webjar 的解决方案不再适用于 SwaggerUI 版本 >= 4.1.3，因为该url参数被忽略（请参阅此问题/发行说明）。URL 必须在 HTML 中指定，或者url需要在 HTML 中启用参数。因此，目前的解决方案似乎是直接解包 UI、更新index.html和服务，而不是通过 webjar。

于 2022-02-22T08:01:22.603 回答