Cannot generate documentation for requests whose content-type is form-data and urlencoded

[shaunhurryup]

I did read the documentation and QA, but didn't find the answers :-(

Your Environment

• MBP Apple silicon
• maven-plugin

            <plugin>
                <groupId>com.ly.smart-doc</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>3.0.4</version>
                <configuration>
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                    <projectName>${project.description}</projectName>
                </configuration>
                <executions>
                    <execution>
                        <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
                        <phase>compile</phase>
                        <goals>
                            <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                            <goal>openapi</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

• smart-doc.json

{
  "outPath": "./src/main/resources/static/doc",
  "pathPrefix": "/api",
  "allInOne": true
}

• build tool version(maven or gradle): maven
• jdk version: 8

Expected Behavior

The type, example, and description of the request parameters should be in the /api/example/goods-form-urlencoded.post.requestBody.content.application/x-www-form-urlencoded

"/api/example/goods-form-urlencoded": {
      "post": {
        "summary": "指定 content-type=application/x-www-form-urlencoded 请求头以添加商品",
        "deprecated": false,
        "tags": [
          "管理 商品信息"
        ],
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                    + There should be the content of the request parameters
                    + There should be the content of the request parameters
                    + There should be the content of the request parameters
               },
              "examples": {
                "json": {
                  "summary": "test data",
                  "value": "curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -i '/api/example/goods-form-urlencoded' --data 'type=electronics&name=iPhone 15 Pro Max&price=9999&secondHand=false&description=这是一款新款 iPhone，性能强劲，拍照效果好，电池续航长&tags=[\"新款\", \"性能强劲\", \"拍照效果好\", \"电池续航长\"]'"
                }
              }
            }
          }
        },

Current Behavior

The type, example, and description of the request parameters are set in /api/example/goods-form-urlencoded.post.parameters incorrectly

"/api/example/goods-form-urlencoded": {
      "post": {
        "summary": "指定 content-type=application/x-www-form-urlencoded 请求头以添加商品",
        "deprecated": false,
        "tags": [
          "管理 商品信息"
        ],
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                    + There should be the content of the request parameters
                    + There should be the content of the request parameters
                    + There should be the content of the request parameters
               },
              "examples": {
                "json": {
                  "summary": "test data",
                  "value": "curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -i '/api/example/goods-form-urlencoded' --data 'type=electronics&name=iPhone 15 Pro Max&price=9999&secondHand=false&description=这是一款新款 iPhone，性能强劲，拍照效果好，电池续航长&tags=[\"新款\", \"性能强劲\", \"拍照效果好\", \"电池续航长\"]'"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {},
                "examples": {
                  "json": {
                    "summary": "test data",
                    "value": "Return void."
                  }
                }
              }
            }
          }
        },
        "operationId": "api-example-goods-form-urlencoded-POST",
        + But it's incorrectly set here
        "parameters": [
          {
            "schema": {
              "format": "enum",
              "type": "string",
              "enum": [
                "FRUIT",
                "ELECTRONICS",
                "FOOD",
                "DRINK",
                "OTHER"
              ]
            },
            "in": "query",
            "description": "商品类型",
            "required": true,
            "example": "electronics",
            "name": "type"
          },
          {
            "schema": {
              "format": "string",
              "type": "string"
            },
            "in": "query",
            "description": "商品名称",
            "required": true,
            "example": "iPhone 15 Pro Max",
            "name": "name"
          },
          {
            "schema": {
              "format": "int32",
              "type": "integer"
            },
            "in": "query",
            "description": "商品价格",
            "required": true,
            "example": "9999",
            "name": "price"
          },
          {
            "schema": {
              "format": "boolean",
              "type": "boolean"
            },
            "in": "query",
            "description": "是否二手",
            "required": true,
            "example": "false",
            "name": "secondHand"
          },
          {
            "schema": {
              "format": "string",
              "type": "string"
            },
            "in": "query",
            "description": "商品描述",
            "required": false,
            "example": "这是一款新款 iPhone，性能强劲，拍照效果好，电池续航长",
            "name": "description"
          },
          {
            "schema": {
              "type": "object"
            },
            "in": "query",
            "description": "商品标签",
            "required": false,
            "example": "[新款, 性能强劲, 拍照效果好, 电池续航长]",
            "name": "tags"
          }
        ]
      }
    },

Context

/**
 * 指定 content-type=application/x-www-form-urlencoded 请求头以添加商品
 */
@PostMapping(value = "/goods-form-urlencoded", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
public void addGoodByFormUrlencoded(AddGoodRequestJson json) {
    // 实现逻辑
}

@Data
public class AddGoodRequestJson {
    /**
     * 商品类型
     *
     * @mock electronics
     */
    @NotNull
    private GoodType type;

    /**
     * 商品名称
     *
     * @mock iPhone 15 Pro Max
     */
    @NotNull
    private String name;

    /**
     * 商品价格
     *
     * @mock 9999
     */
    @NotNull
    private int price;

    /**
     * 是否二手
     *
     * @mock false
     */
    @NotNull
    private boolean secondHand;

    /**
     * 商品描述
     *
     * @mock 这是一款新款 iPhone，性能强劲，拍照效果好，电池续航长
     */
    private String description;

    /**
     * 商品标签
     *
     * @mock ["新款", "性能强劲", "拍照效果好", "电池续航长"]
     */
    private String[] tags;
}

[shalousun]

@shaunhurryup According to the code you provided, the OpenAPI generated by smart-doc can be normally displayed by the latest version of springdoc-openapi-starter-webmvc-ui, and requests can also be processed normally. The OpenAPI generated by smart-doc is based on the 3.0.3 protocol, not Swagger 2. Of course, due to data acquisition reasons, smart-doc will make some sacrifices in the implementation of the components section, which will affect certain code generation.

[shalousun]

@shaunhurryup Currently, smart-doc is optimal for scenarios that use JSON requests, but its handling of schemas and components is not very complete. This can affect scenarios where OpenAPI is used to generate code. The documentation display can be used normally. If you are familiar with OpenAPI, you are welcome to participate in the joint improvement.

[shaunhurryup]

@shaunhurryup According to the code you provided, the OpenAPI generated by smart-doc can be normally displayed by the latest version of springdoc-openapi-starter-webmvc-ui, and requests can also be processed normally. The OpenAPI generated by smart-doc is based on the 3.0.3 protocol, not Swagger 2. Of course, due to data acquisition reasons, smart-doc will make some sacrifices in the implementation of the components section, which will affect certain code generation.

1. can be normally displayed

Yeah, the JSON output can be rendered by any UI tools that support the OpenAPI specification. However, it is displayed using query parameters instead of x-www-form-urlencoded.

By Apifox

I import json output to Postman, it display query parameters too

2. request can be processed

A request of type query parameters cannot be answered correctly by a server that defines type application/x-www-form-urlencoded

You can see my json output if you want~

openapi.json

[shalousun]

@shaunhurryup We have tested it, and the parameters generated by openapi ui are also placed in the parameters. Our processing method is to directly split the parameter fields, not using ref. There may be no mandatory requirements for the presentation of application/x-www-form-urlencoded. It does indeed treat x-www-form-urlencoded types as key=value from the browser's perspective. Whether the community will optimize it to the way you want remains to be seen, as I don't have time to deal with it recently. Smart-doc initially leaned towards the more mainstream JSON request method at present, so its support for form requests will be somewhat weaker.