Request body does not show up in curl example with OpenApi3 + widdershins + shins

user_4389737 0
Viewed 594

I am generating API documentation for our Java endpoints. I am using widdershins to convert our openAPI3.0 yaml file to markdown. Then, I am using shins to convert the markdown file to html. The request body for all of our endpoints does not appear in the generated cURL examples. Why is this? This defeats the purpose of having cURL examples because copying and pasting a cURL example without the required body will not work. Can anyone recommend a workaround or alternative tool that generates good documentation with complete cURL examples?

Example endpoint from our openAPI.yaml file...

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'

This is the documentation our toolchain generates from this yaml file... enter image description here We would like to add a line just like the one below (grey highlight) to our cURL examples. This is a chunk from the markdown file that Widdershins produces from our openAPI yaml file. I manually added the –“d

enter image description here

This stack overflow Q/A suggests the answer is it is impossible to include a body parameter in a code example using swagger or openAPI. Is this correct? If so, why is this the case? What's the reasoning?

Cheers, Gideon

widdershins swagger openapi api
2 Answers

I also had the same problem. As a result of trial and error, it was found that the behavior displayed on curl varies depending on the in value.

Please look at the ParameterIn enum.

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

I tried by like below at first time:

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

But name return like "HEADER", So swagger(or OpenAPI) recognized to header. It should be lower character like "header" follow ParameterIn enum.

So, you can fix it like this

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

or

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

I also encountered the same problem and I did a little digging. It turns out I had to set options.httpSnippet option in widdershins to true so that the requestBody params will show up. However, setting that to true just shows the params if content type is of application/json. For multipart-form-data, you need to set options.experimental to true as well.

Unfortunately, there is a bug in widdershins for handling application/x-www-form-urlencoded content-type.. I created a PR for it which you can probably manually patch on the widdershins package. PR link: https://github.com/Mermade/widdershins/pull/492/files

user_52924850
Related