时间戳

首页 > 解决方案 > 请求正文没有出现在 OpenApi3 + widdershins + shins 的 curl 示例中

api - 请求正文没有出现在 OpenApi3 + widdershins + shins 的 curl 示例中

问题描述

我正在为我们的 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 参数。这个对吗？如果是这样，为什么会这样？原因是什么？

干杯，吉迪恩

标签： apiswaggeropenapiwiddershins

解决方案

我也遇到了同样的问题，我做了一点挖掘。事实证明，我必须将 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

推荐阅读