api - 请求正文未显示在带有 OpenApi3 + widdershins + shins 的 curl 示例中

Question

我正在为我们的 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 文件中的一个 block 。我手动添加了-“d

这个堆栈溢出 Q/A 表明答案是不可能在使用 swagger 或 openAPI 的代码示例中包含主体参数。这样对吗？如果是这样，为什么会这样？这是什么道理？

干杯，基甸

Answer 1

我也遇到了同样的问题。经过反复试验，发现 curl 上显示的行为因 in 值而异。

请查看 ParameterIn 枚举。

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

我第一次尝试如下:

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

但是名称返回像“HEADER”，所以 swagger(或 OpenAPI)被识别为标题。它应该是小字符，如“header”跟在 ParameterIn 枚举之后。

所以，你可以这样修复它

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

或

new Parameter().name("foo").in("header")