如何使用自定义分隔符序列化OpenAPI查询对象？

Unfortunately, OpenAPI 3.0.1 does not support defining custom delimiters for query parameters out of the box. The style and explode options only cover predefined serialization behaviors, and there’s no built-in setting to replace commas with : and | for object-type query parameters like your origin field.

Here are the practical workarounds to achieve your desired curl command format:

1. Treat origin as a String Parameter #

The simplest approach is to define origin as a plain string instead of an object. This lets users input the exact format you need (city:atlanta|zip:303) and will generate the curl command you want in Swagger Editor. You’ll just need to document the expected format clearly:

openapi: 3.0.1
info:
  title: My API
  version: v1
paths:
  /users:
    get:
      parameters:
        - in: query
          name: offset
          schema:
            type: integer
          description: The number of items to skip before starting to collect the result set
        - in: query
          name: limit
          schema:
            type: integer
          description: The numbers of items to return
        - in: query
          name: origin
          schema:
            type: string
          description: Filter by origin. Format must be `city:<city-name>|zip:<zip-code>` (e.g., `city:atlanta|zip:303`)
      responses:
        '200':
          description: A list of users

When you use "Execute" in Swagger Editor now, it will generate the curl command with your custom origin format as long as you input the string correctly.

2. Adapt the Backend to Parse Default Format #

If you want to keep the object structure in your OpenAPI spec (for validation and documentation clarity), you can leave the parameter definition as-is, but modify your API backend to parse the default comma-separated format (city,atlanta,zip,303) into your desired structure. This won’t change the curl command generated by Swagger Editor, but your API will still handle the request correctly.

3. Customize Swagger UI Serialization (Advanced) #

If you absolutely need Swagger Editor to generate the custom format automatically, you’d have to customize the Swagger UI code. This involves overriding the parameter serialization logic for object-type query parameters to use : and | instead of commas. This is more complex and requires familiarity with Swagger UI’s underlying codebase.

内容的提问来源于stack exchange，提问作者Mažas