Feature: expose runtime OpenAPI operation metadata for schema introspection

[0xBigBoss]

We found it useful for generated OpenAPI commands to retain runtime operation metadata so schema inspection can resolve mounted operations directly from the mounted spec.

The use case was:

• mounted OpenAPI-backed commands
• runtime schema lookup for a specific operation
• introspection of params, request body, and response shape

In our fork, we attached runtime operation metadata to generated commands so the framework could expose richer per-command schema information without relying on a stale baked manifest.

Reference patch:

• 0xBigBoss/incur@081ad15

Would you be open to upstreaming runtime OpenAPI metadata on generated commands so mounted operations can participate in schema introspection more cleanly?

[jxom]

I think you're looking for --schema?

[0xBigBoss]

I don’t think --schema is quite the same thing.

--schema gives the raw input/output schema for the resolved command, but it drops the original OpenAPI operation context. For a generated command like api createUser, it can tell you there is a name: string option, but not that the command came from POST /users, has a request body, returns a specific response schema, or mutates state.

What the patch adds is runtime OpenAPI metadata on generated commands so schema can describe them like first-class commands. That means introspection can include operationId, httpMethod, path, request/response schema, and mutates/destructive, instead of only the flattened CLI flags.

So the value isn’t just “more docs”. It’s preserving operation identity during OpenAPI command generation so mounted OpenAPI commands can participate in the richer command introspection surface instead of losing that context.

example

  {
    "options": {
      "type": "object",
      "properties": {
        "name": { "type": "string" }
      },
      "required": ["name"]
    },
    "output": {
      "type": "object"
    }
  }

  {
    "name": "api createUser",
    "description": "Create a user",
    "mutates": true,
    "openapi": {
      "operationId": "createUser",
      "httpMethod": "POST",
      "path": "/users",
      "requestBody": {
        "type": "object",
        "properties": {
          "name": { "type": "string" }
        },
        "required": ["name"]
      },
      "response": { "type": "object" }
    },
    "schema": {
      "options": {
        "properties": {
          "name": { "type": "string" }
        }
      },
      "body": {
        "type": "object",
        "properties": {
          "name": { "type": "string" }
        },
        "required": ["name"]
      },
      "output": { "type": "object" }
    }
  }