从 JavaDoc 生成 OpenAPI 描述

问题描述

我有一个应用程序，它提供了一个带有 JAX-RS（用于 RESTful Web 服务的 Java API / JSR-311）的 API。

出于文档目的，我根据 OpenAPI-Specification 提供了一个 URL，该 URL 由 Eclipse MicroProfile OpenAPI 生成。

一切正常，除了方法和参数的描述，我需要添加两次 - 在注释和 JavaDoc 中：

/**
 * Finds all resources with the given prefix.
 *
 * @param prefix
 *            the prefix of the resource
 * @return the resources that start with the prefix
 */
@GET
@Path("/find/{prefix}")
@Produces(MediaType.APPLICATION_JSON)
@Operation(description = "Finds all resources with the given prefix")
public List<Resource> find(
        @Parameter(description = "The prefix of the resource") 
        @PathParam("prefix") final String prefix) {
    ...
}

我知道没有运行时库可以读取 JavaDoc（因为它不是类文件的一部分），这是注释的主要原因。但我想知道 OpenAPI 生成工具之一（Swagger、Eclipse MicroProfile OpenAPI 等）是否还有其他选项可以阻止我手动同步文档？

例如，在另一个项目中，我使用 doclet 序列化 JavaDoc 并将其存储在类路径中，以便在运行时向用户呈现 Beans API 文档。但即使我在这里使用了这个 doclet，我也看不到在运行时向 OpenAPI 库提供 JavaDoc 描述的选项。

我知道我可以放弃 JavaDoc，如果我的 API 用户只使用“外语”，因为他们无论如何都看不到 JavaDoc。但是如果 API 的另一端是 JAX-RS 客户端会发生什么？在这种情况下，JavaDoc 将是一个巨大的支持。

解决方法

暂无找到可以解决该程序问题的有效方法，小编努力寻找整理中！

如果你已经找到好的解决方法，欢迎将解决方案带上本链接一起发送给小编。

小编邮箱:dio#foxmail.com (将#修改为@）

jax-rs openapi swagger