如何用http4k暴露swagger UI？

Question

我正在用HTTP4k构建一个微服务。http4k框架 用他们 合同API. 我可以很容易地暴露的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 上面指定的。

一个理想的API应该是这样的

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

Answer 1

http4k没有提供OpenApi UI的版本。你可以通过以下方式轻松地发布一个版本的UI。

1. 将 OpenApi UI 解压到 srcmainresourcespublic 文件夹中。
2. 使用 static 路由块来服务器资源。这里有一个例子。https:/github.comhttp4khttp4k by-exampleblob22dcc9a83c497253c29830d5bc981afa5fbbe4ffsrcmainkotlinverysecuresystemsSecuritySystem.kt#L61。

Answer 2

经过一番搜索，我用以下组合实现了这一目标。网络罐 和http4k的静态路由。

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

• index.html 是一个静态的Swagger UI入口点，由一个web jar提供。
• url query param告诉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"))
)

我们还必须包括 嗖嗖嗖-ui webjar 作为我们的依赖。这是一个Gradle指令。

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

参见webjars网站上的Maven（以及更多）指令。

请注意 swaggerUi 处理程序假定其绑定到 / 整个服务的根路径。不过，这一点很容易解决。