nearform / openapi-transformer-toolkit

Automate design-first API workflows by generating schemas and types from OpenAPI specs.
21 stars 4 forks source link

oas2tson return path parameters as array instead of objects #293

Open princeede opened 3 months ago

princeede commented 3 months ago

Using this toolkit to generate TS JSON schemas returns the path parameters as an array instead of objects for each path.

For example, the yaml file below

...
paths:
  /pet/findByStatus:
    get:
      tags:
        - pet
      summary: Finds Pets by status
      description: Multiple status values can be provided with comma separated strings
      operationId: findPetsByStatus
      parameters:
        - name: status
          in: query
          description: Status values that need to be considered for filter
          required: false
          explode: true
          schema:
            type: string
            default: available
            enum:
              - available
              - pending
              - sold
...

will generate the output

export const PetFindByStatus = {
  get: {
    tags: ["pet"],
    summary: "Finds Pets by status",
    description:
      "Multiple status values can be provided with comma separated strings",
    operationId: "findPetsByStatus",
    parameters: [
      {
        name: "status",
        in: "query",
        description: "Status values that need to be considered for filter",
        required: false,
        explode: true,
        schema: {
          type: "string",
          default: "available",
          enum: ["available", "pending", "sold"],
        },
      },
    ],
    ...
} as const;

This means the output cannot be used directly in fastify schemas without writing some scripts to extract headers/path/query/cookies based on the open API standard describing parameters

Instead of an array, parameters should return an object in the format

...
 parameters: {
      headers: {...},
      path: {...},
      query: {...},
      cookies: {...}

        required: [...],
        type: 'object'
      }
    }
...
jmjf commented 5 days ago

I think this is related to issues discussed in #305 and https://github.com/nearform/openapi-transformer-toolkit/pull/318.

FWIW, my solution to this is to write query, header, etc., parameters in schemas then $ref the schemas in paths and pass them to query, etc., in Fastify. For example:

components:
   schemas:
      ExampleQuery:
         description: I can provide a detailed description that shows up in Redocly-generated docs.
         type: object
         required:
            - param1
         properties:
            param1:
               # parameter details
            param2:
               # parameter details
   parameters:
      ExampleQueryParameter:
         name: exampleQuery
         in: query
         schema:
            $ref: '#/components/schemas/ExampleQuery'
      ExampleHeaderParameter:
         in: header
         # etc.
paths:
   get:
      parameters:
         - $ref: '#components/parameters/ExampleQueryParameter
         - $ref: '#/components/parameters/ExampleHeaderParameter
      # etc.
// in Fastify schema
parameters: {
    query: ExampleQuery,
    headers: ExampleHeader,
    // etc.
}

I haven't used this approach with cookies, but it works for header, path, and query parameters.