3

我正在为我们的 Java 端点生成 API 文档。我正在使用 widdershins 将我们的 openAPI3.0 yaml 文件转换为 markdown。然后，我使用 shins 将 markdown 文件转换为 html。我们所有端点的请求正文都没有出现在生成的 cURL 示例中。为什么是这样？这违背了拥有 cURL 示例的目的，因为复制和粘贴没有所需正文的 cURL 示例将不起作用。任何人都可以推荐一种解决方法或替代工具，以生成带有完整 cURL 示例的良好文档吗？

我们的 openAPI.yaml 文件中的示例端点...

post:
  tags:
  - Tools
  description: Installs a tool on a user's account
  operationId: Install Tool
  requestBody:
    description: UserTool object that needs to be installed on the user's account
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/UserTool'
    required: true
  parameters:
  responses:
    default:
      description: default response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Message'

这是我们的工具链从这个 yaml 文件生成的文档...... 在此处输入图像描述 我们想在我们的 cURL 示例中添加一行，就像下面的行（灰色突出显示）一样。这是 Widdershins 从我们的 openAPI yaml 文件生成的 markdown 文件中的一个块。我手动添加了-“d

在此处输入图像描述

这个堆栈溢出问答表明答案是不可能在使用 swagger 或 openAPI 的代码示例中包含 body 参数。这个对吗？如果是这样，为什么会这样？原因是什么？

干杯，吉迪恩

4

2 回答 2

0

我也遇到了同样的问题，我做了一点挖掘。事实证明，我必须将 widdershins 中的 options.httpSnippet 选项设置为 true，以便显示 requestBody 参数。但是，如果内容类型是 application/json，则将其设置为 true 只会显示参数。对于 multipart-form-data，您还需要将 options.experimental 设置为 true。

不幸的是，widdershins 中有一个用于处理 application/x-www-form-urlencoded 内容类型的错误。我为它创建了一个 PR，您可以手动修补 widdershins 包。公关链接：https ://github.com/Mermade/widdershins/pull/492/files

于 2022-01-28T02:26:10.527 回答
0

我也有同样的问题。经过反复试验，发现 curl 上显示的行为取决于 in 值。

请查看 ParameterIn 枚举。

public enum ParameterIn {
    DEFAULT(""),
    HEADER("header"),
    QUERY("query"),
    PATH("path"),
    COOKIE("cookie");

我第一次尝试如下：

new Parameter().name("foo").in(ParameterIn.HEADER.name())

但是名称返回像“HEADER”，所以招摇（或OpenAPI）识别到标题。它应该是像“标题”这样的较低字符，跟随 ParameterIn 枚举。

所以，你可以像这样修复它

new Parameter().name("foo").in(ParameterIn.HEADER.toString())

或者

new Parameter().name("foo").in("header")
于 2021-09-17T05:31:00.233 回答