export operations interface

[gr2m]

As suggested in my comment at #236 (comment), I'd prefer to export an operations interface, besides paths and components.

Instead of setting the types for each operation in the paths object, I'd reference an operation key using the operations ID`. In the example of the GitHub OpenAPI schema,

export interface paths {
  "/": {
    /**
     * Get Hypermedia links to resources accessible in GitHub's REST API
     */
    get: {
      // ...
    }
  }
}

would result in

export interface paths {
  "/": {
    get: operations["meta/root"]
  }
}
export interface operations {
  /**
   * Get Hypermedia links to resources accessible in GitHub's REST API
   */
  "meta/root": {
     // ...
  }
}

operationIds are great to generate SDK methods. Having the operation export with direct access to operation types would make it easier to access the operation types for parameters and responses

[drwpow]

I‘m looking at the spec at this seems like it‘d be the first departure we‘d have from the OpenAPI schema format.

My only concern is that the paths generated types match 1:1 with the original schema. And it looks like the way get: operations["meta/root"] is used, it seems like the paths interface the same way. So I’d be in favor of it as long as users could still type paths["/"]["get"]["meta/root"] if they wanted to, because that‘s their spec.

But what is the advantage here? Would this primarily save some typing to use operations["meta/root"] rather than paths["/"]["get"]["meta/root"]?

[gr2m]

I don't think this change should break anything. paths["/"]["get"] would point to the same type as operations["meta/root"], it would just add an alternative means of accessing the operation types

For example with the GitHub OpenAPI, it can by quite cumbersome to access them if the paths get long and complicated:

paths["/orgs/{org}/teams/{team_slug}/discussions/{discussion_number}/comments/{comment_number}/reactions/{reaction_id}"]["delete"]

With the change I suggest, the type above would be accessible with this alias:

operations["reactions/delete-for-team-discussion-comment"]

[drwpow]

Cool. Thanks for clarifying, and for providing a better usecase. In that case I’m in favor of this, and agree that‘d be an improvement. Also, I think as operationId isn‘t a super-used aspect of OpenAPI as far as I‘m aware, I’m fine with adding some QoL stuff on top of that.

[gr2m]

cool I'll look into it thanks!