fix: refactor toOperations to read path level parameter definitions

[fdoflorenzano]

We noticed that the docs don't always display a box with the required path params for an operation. v1 operations don't display it while v2 do:

Diving a little deeper we realize that it's just a difference between on where the path params are defined between versions. The toOperations function currently expects all parameters, query and path, to be included in the parameters field of the operation. Meaning:

{
  "paths": {
    "/packages/{package_slug_perm}/vulnerabilities/osv/": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "package_slug_perm",
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9]+$"
            },
            "required": true
          }
        ]
      }
    }
  }
}

Which is true for the V2 schema definition, but not for the V1. V1 seems to only include query params at that level, while path params are defined at the path level. Meaning:

{
  "paths": {
    "/audit-log/{owner}/": {
      "get": {
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "A page number within the paginated result set.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ]
      },
      "parameters": [
        {
          "name": "owner",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ]
    },
}

This PR refactors toOperations to handle this option. It now does so by and keeping track of operations being parsed and organizing them based on path. Whenever a path level parameter definition is found, it's saved and updates any already processed operations for that path. And whenever an operation is processed, it checks for any found parameters for that path and includes them into the operation.

This not only fixes the display of the path params box in the site, but also make path params definitions available for all operations. A necessary piece for the API Sandbox work.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
cloudsmith-docs	Ready	Preview, Comment	Jan 15, 2026 4:17pm

[runemadsen]

Nice! The reason for this happening is that the V1 schema is actually converted from an older Swagger version to Open API version 3, and I'm guessing that this is a result of that. Great fix!

[aptkingston]

LGTM!