使用 OpenAPI 3 记录端点

https://javalin.io/tutorials/openapi-example

我们将构建一个User包含五个操作的 CRUD API，并为其生成 OpenAPI 规范。示例代码片段包含 Java 和 Kotlin 代码，每种语言的项目均可在 GitHub上找到。

依赖项
首先，我们需要创建一个包含依赖项的 Maven 项目：（→ 教程）

我们还需要为 Open API 注释添加一个构建部分：

构建 API
让我们定义主类。我们将在这里放置服务器和 OpenAPI 配置：

package io.javalin.example.kotlin

import io.javalin.Javalin
import io.javalin.apibuilder.ApiBuilder.delete
import io.javalin.apibuilder.ApiBuilder.get
import io.javalin.apibuilder.ApiBuilder.patch
import io.javalin.apibuilder.ApiBuilder.path
import io.javalin.apibuilder.ApiBuilder.post
import io.javalin.example.kotlin.user.UserController
import io.javalin.openapi.OpenApiInfo
import io.javalin.openapi.plugin.OpenApiPlugin
import io.javalin.openapi.plugin.redoc.ReDocPlugin
import io.javalin.openapi.plugin.swagger.SwaggerPlugin

fun main() {

Javalin.create { config ->
    config.registerPlugin(OpenApiPlugin { pluginConfig ->
        pluginConfig.withDefinitionConfiguration { version, definition ->
            definition.withOpenApiInfo { info: OpenApiInfo ->
                info.title = "Javalin OpenAPI example"
            }
        }
    })
    config.registerPlugin(SwaggerPlugin())
    config.registerPlugin(ReDocPlugin())
    config.router.apiBuilder {
        path("users") {
            get(UserController::getAll);
            post(UserController::create);
            path("{userId}") {
                get(UserController::getOne);
                patch(UserController::update);
                delete(UserController::delete);
            }
        }
    }
}.start(7001)

println("Check out ReDoc docs at http://localhost:7001/redoc")
println("Check out Swagger UI docs at http://localhost:7001/swagger")

}
我们通过调用 来启用 OpenAPI 插件config.plugins.register，并在该方法中完成所有配置。如前所述，我们将同时注册 ReDoc 和 Swagger UI（用于为我们的 API 生成 Web UI），但您在生产环境中很可能只会使用其中之一。

上面代码片段中的 API 定义引用了一个名为 的东西UserController，但它并不存在。让我们创建一个框架：

package io.javalin.example.kotlin.user

import io.javalin.http.Context

object UserController {

fun create(ctx: Context) {
}

fun getAll(ctx: Context) {
}

fun getOne(ctx: Context) {
}

fun update(ctx: Context) {
}

fun delete(ctx: Context) {
}

}
这为User对象定义了一个简单的 CRUD API。

添加注释
为了改进文档，我们可以向处理程序添加注释。

让我们从以下开始Get users：

@OpenApi(
summary = “Get all users”,
operationId = “getAllUsers”,
tags = [“User”],
responses = [OpenApiResponse(“200”, [OpenApiContent(Array::class)])],
path = “/users”,
methods = [HttpMethod.GET]
)
fun getAll(ctx: Context) {
ctx.json(UserService.getAll())
}
我们创建了一个UserService和一个User类。这与 OpenAPI 关系不大，因此本教程中不会展示它们，不过所有内容都可以在GitHub上找到。

让我们来看看不同的属性：

摘要- 将用作标题，无论是在网络文档还是在客户端文档中
operationId - 如果您从 OpenAPI 规范生成客户端，这将是方法名称
标签- 用于对端点进行分组
响应- 描述端点可以响应的状态码和数据模型。此特定端点只能使用对象数组进行响应User。
让我们看看启动服务器后我们的文档是什么样子的：

OpenAPI 截图

太棒了！我们有一个User类别和一个 Schema 。我们可以通过点击它来进一步User探索端点：Get all users

OpenAPI 截图

我们看到它不需要任何参数，并且它将以 200 和一个User对象数组进行响应。

如果您已经克隆了 repo，您​​可以尝试Try it out立即单击该按钮，这将为您提供四个用户的数组。

让我们记录一下Update user端点，它接受一些输入并有多个响应：

@OpenApi(
summary = “Update user by ID”,
operationId = “updateUserById”,
tags = [“User”],
pathParams = [OpenApiParam(“userId”, Int::class, “The user ID”)],
requestBody = OpenApiRequestBody([OpenApiContent(NewUserRequest::class)]),
responses = [
OpenApiResponse(“204”),
OpenApiResponse(“400”, [OpenApiContent(ErrorResponse::class)]),
OpenApiResponse(“404”, [OpenApiContent(ErrorResponse::class)])
],
path = “/users/{userId}”,
methods = [HttpMethod.PUT]
)
与我们之前记录的端点相比，该端点还有两个属性：

pathParams - 这些定义了 Javalin 的路径参数。此外还有queryParams和formParams。
requestBody - 此端点需要 JSON 对象作为请求主体
此端点还有两个响应：

如果您提供无效userId或NewUserRequest反对意见，您将得到 400。
如果您尝试更新不存在的用户，您将收到 404。
差不多就是这样！
示例repo 包含一个完全可用的 API，因此如果您克隆它，您就可以使用Try it out 每个端点的按钮。