OpenAPI SDK readiness

Slack Web API OpenAPI spec score

Octri scored the public spec at https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/slack_web_openapi_v2.json for what a code generator can do with it. This is a reading of the document, not a grade of the API.

8.3/ 10
Strong

174 operations · 48 models · 56 tags · Swagger 2.0

Scored 14 September 2026 · fingerprint 742a5c977180… · spec version 1.7.0 · server slack.com

Document last changed 14 September 2026.

Generate a TypeScript SDK from a spec like thisSee the fourteen rulesScore your own spec

Where the points went

Every rule, heaviest first, with what it cost this document and how much of the surface it touched. Open a row for the locations.

  1. Successful responses declare a schema2.0Clean174 operations clean

    Without a response schema every method returns `unknown`/`any`, so callers get no types and no autocompletion.

    What this rule checks

  2. Shared models live in components and are $ref'd2.00.5 lost7 of 174 operations

    Inline object schemas become anonymous per-operation types. The same model inlined in 20 operations generates 20 near-identical types instead of one.

    • app_id, request_id, team_id An identical inline object (3 fields) appears in 2 operations. Move it to `components.schemas` and $ref it, or the SDK generates 2 separate types.
    • channel_id, group_id, team_id, token An identical inline object (4 fields) appears in 2 operations. Move it to `components.schemas` and $ref it, or the SDK generates 2 separate types.
    • callstack, error, ok An identical inline object (3 fields) appears in 70 operations. Move it to `components.schemas` and $ref it, or the SDK generates 70 separate types.
    • channel, ok, ts An identical inline object (3 fields) appears in 2 operations. Move it to `components.schemas` and $ref it, or the SDK generates 2 separate types.
    • callstack, error, needed, ok An identical inline object (5 fields) appears in 14 operations. Move it to `components.schemas` and $ref it, or the SDK generates 14 separate types.
    • 2 more, not listed here.

    What this rule checks

  3. Generated public names do not collide2.0Clean174 operations clean

    When authored identifiers collapse to the same shared public name, the generator must silently rename one method; callers otherwise cannot predict the SDK surface from the spec.

    What this rule checks

  4. Every path placeholder has a parameter1.5Clean174 operations clean

    An undeclared `{id}` placeholder cannot become a typed method argument, so the generated request path is incomplete or uncompilable.

    What this rule checks

  5. Every operation declares an operationId1.0Clean174 operations clean

    Without one the generator synthesizes a name from the path, which changes whenever the path does. That is a silent breaking change for callers.

    What this rule checks

  6. operationIds read as method names1.01.0 lost173 of 174 operations

    The id becomes the method name. `ActionsActionsGet` generates `client.actions.actionsActionsGet()`; `getActions` generates `client.actions.get()`.

    • POST /admin.apps.approve `admin_apps_approve` reads better as `createAdminAppsApprove` at the call site.
    • GET /admin.apps.approved.list `admin_apps_approved_list` reads better as `listAdminAppsApproved` at the call site.
    • GET /admin.apps.requests.list `admin_apps_requests_list` reads better as `listAdminAppsRequests` at the call site.
    • POST /admin.apps.restrict `admin_apps_restrict` reads better as `createAdminAppsRestrict` at the call site.
    • GET /admin.apps.restricted.list `admin_apps_restricted_list` reads better as `listAdminAppsRestricted` at the call site.
    • 168 more, not listed here.

    What this rule checks

  7. Operations carry a summary or description1.0Clean174 operations clean

    Operation prose becomes the method's doc comment, the text an IDE shows on hover.

    What this rule checks

  8. Request bodies are documented1.0Clean174 operations clean

    Body field descriptions become the doc comments on generated parameters; without them the SDK ships undocumented arguments.

    What this rule checks

  9. Failure responses are declared1.0Clean174 operations clean

    Declared error schemas become typed errors. Without them every failure surfaces as an untyped generic error.

    What this rule checks

  10. Operations are tagged1.0Clean174 operations clean

    Tags drive namespacing. Untagged operations fall back to a path segment, producing lopsided or `misc` namespaces.

    What this rule checks

  11. No duplicate or equivalent paths1.0Clean174 paths clean

    Paths differing only in parameter NAME are the same route to a server; the generated SDK ends up with two methods that call the same endpoint.

    What this rule checks

  12. Authentication is described1.0CleanDeclared

    Security schemes generate the SDK's auth configuration. A spec without them produces a client with no way to authenticate.

    What this rule checks

  13. Parameters explain their purpose0.750.24 lost25 of 174 operations

    Parameter descriptions become IDE hints on generated method arguments; bare names force SDK users back to the API reference.

    • GET /admin.apps.approved.list#query:team_id `team_id` has no description, so the generated argument has no IDE guidance.
    • GET /admin.apps.approved.list#query:enterprise_id `enterprise_id` has no description, so the generated argument has no IDE guidance.
    • GET /admin.apps.requests.list#query:team_id `team_id` has no description, so the generated argument has no IDE guidance.
    • GET /admin.apps.restricted.list#query:team_id `team_id` has no description, so the generated argument has no IDE guidance.
    • GET /admin.apps.restricted.list#query:enterprise_id `enterprise_id` has no description, so the generated argument has no IDE guidance.
    • 20 more, not listed here.

    What this rule checks

  14. A server URL is declared0.5CleanDeclared

    Without a server URL the generated client must ship with an empty or placeholder base URL, adding setup work and easy production misconfiguration.

    What this rule checks

What 8.3 means for an SDK

A strong reading, and the three rules that decide most of it.

A generator has what it needs here: typed methods, named models and doc comments that say something. What is left is polish, and it can wait until after the first release.

Three rules carry six of the 10 points between them. On this document they took 0.46.

Clean

Successful responses declare a schema

174 operations clean

−0.5

Shared models live in components and are $ref'd

7 of 174 operations

Clean

Generated public names do not collide

174 operations clean

What to change first

Every rule that deducted, in the order they cost.

  1. Shared models live in components and are $ref'd

    Move the shape into components.schemas once and $ref it from each operation that returns or accepts it.

  2. operationIds read as method names

    Name the id for the action, not the route. The audit suggests one per operation and can apply it. Inside Octri this one has a one-click fix.

  3. Parameters explain their purpose

    Describe what the parameter does and what a valid value looks like. One line each. Inside Octri this one has a one-click fix.

Score your own spec in OctriRun the free audit

Where to go next

The spec at raw.githubusercontent.comis public. Octri keeps the `info` block, the score, and up to five sample finding locations per rule. The document itself is not stored and is not served from here. The audit predicts what an SDK generator can do with the description; it is not a security review, an uptime measurement or a critique of the API’s design. This page is not affiliated with Slack Web API or Slack developer relations.