如何使用http4k公开傲慢的UI？

Question

我正在使用http4k框架的合约API构建一个微型服务。我可以很容易地在eg上公开这个傲慢的API描述JSON。/swagger.json与

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

是否有一种简单的方法来公开傲慢的用户界面，以便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 += ...
}

Answer 1

到了http4k 4.28.1.0，现在有了一种方法来做到这一点。请参阅摘自此文档页的以下代码

package guide.howto.create_a_swagger_ui

import org.http4k.contract.contract
import org.http4k.contract.meta
import org.http4k.contract.openapi.ApiInfo
import org.http4k.contract.openapi.v3.OpenApi3
import org.http4k.contract.ui.swaggerUi
import org.http4k.core.Body
import org.http4k.core.ContentType
import org.http4k.core.Method.GET
import org.http4k.core.Request
import org.http4k.core.Response
import org.http4k.core.Status.Companion.OK
import org.http4k.core.Uri
import org.http4k.core.with
import org.http4k.lens.string
import org.http4k.routing.routes
import org.http4k.server.SunHttp
import org.http4k.server.asServer

fun main() {
    val greetingLens = Body.string(ContentType.TEXT_PLAIN).toLens()

    // Define a single http route for our contract
    val helloHandler = "/v1/hello" meta {
        operationId = "v1Hello"
        summary = "Say Hello"
        returning(OK, greetingLens to "Sample Greeting")
    } bindContract GET to { _: Request ->
        Response(OK).with(greetingLens of "HI!")
    }

    // Define a contract, and render an OpenApi 3 spec at "/spec"
    val v1Api = contract {
        routes += helloHandler
        renderer = OpenApi3(
            ApiInfo("Hello Server - Developer UI", "99.3.4")
        )
        descriptionPath = "spec"
    }

    // Build a Swagger UI based on the OpenApi spec defined at "/spec"
    val ui = swaggerUi(
        Uri.of("spec"),
        title = "Hello Server",
        displayOperationId = true
    )

    // Combine our api, spec, and ui; then start a server
    // The Swagger UI is available on the root "/" path
    routes(v1Api, ui)
        .asServer(SunHttp(8080))
        .start()
        .block()
}

Answer 2

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

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

• index.html是从web中提供的静态Swagger入口点。
• url查询param告诉swagger从哪里获取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'

请参阅webjars网站上的Maven (及更多)指令。

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

Answer 3

使用webjar的解决方案不再适用于SwaggerUI版本>= 4.1.3，因为url参数被忽略了(参见本期 / 发布说明)。URL必须在HTML中指定，或者需要在HTML中启用url参数。因此，目前的解决方案似乎是解压缩UI，更新index.html，直接通过webjar提供服务。