@zenstackhq/openapi: the example generated specification in the documentation is out of date and provides incorrect syntax

[potion-cellar]

Description and expected behavior The documentation for @zenstackhq/openapi should include up-to-date examples that match the documentation.

In the "Generated API paths" section of the documentation (https://zenstack.dev/docs/reference/plugins/openapi#generated-api-paths), the following syntax is mentioned:

For GET/DELETE operations, the query args is passed as JSON-stringified text in the query parameter q.

This conforms with the functionality of the plugin.

However, below that statement, an example is provided:

Check here for the generated specification for a blogging app.

This example appears to have used an older specification with a different syntax than what the current version of @zenstackhq/openapi. The generated specification does not mirror the GET syntax as described in the documentation.

In the linked example, the OpenAPI document has specified different parameters than what currently get generated, under the paths section for each get method:

      parameters:
        - name: q
          in: query
          required: true
          schema:
            $ref: "#/components/schemas/UserFindUniqueArgs"

What is currently generated by the plugin is:

      parameters:
        - name: q
          in: query
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserFindUniqueArgs"

The example is thus misleading as the actual code samples (as provided by Swagger UI) do not provide working syntax for the plugin's generated GET endpoints, at least with only basic configuration for the latest version (alpha.87).

Screenshots If applicable, add screenshots to help explain your problem.

Environment (please complete the following information):

"@zenstackhq/openapi": "^1.0.0-alpha.87",
"@zenstackhq/runtime": "^1.0.0-alpha.87",
"@zenstackhq/server": "^1.0.0-alpha.87",
"zenstack": "^1.0.0-alpha.87"

"prisma": "^4.11.0",
"@prisma/client": "^4.11.0"

v18.15.0

PostgreSQL 15

[ymc9]

Great catch! I'll fix it soon @potion-cellar

[ymc9]

Fixed with a new sample link!

https://editor.swagger.io/?url=https://gist.githubusercontent.com/ymc9/2888fae6fa60f1c7b26a8c226e6bab2f/raw/a4c78732a158a3436b6d5779695b6ab11a6edcf5/petstore.api.yaml