OpenAPI SDK readiness

Stripe API OpenAPI spec score

Octri scored the public spec at https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json for what a code generator can do with it. This is a reading of the document, not a grade of the API.

6.6/ 10
Mixed

594 operations · 1454 models · 0 tags · OpenAPI 3.0.0

Scored 14 September 2026 · fingerprint f0e0fc8fffbf… · spec version 2026-08-26.dahlia · server api.stripe.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.0Clean594 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 lost20 of 594 operations

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

    • data, has_more, object, url An identical inline object (4 fields) appears in 124 operations. Move it to `components.schemas` and $ref it, or the SDK generates 124 separate types.
    • bank_account, default_for_currency, expand, external_account An identical inline object (5 fields) appears in 2 operations. Move it to `components.schemas` and $ref it, or the SDK generates 2 separate types.
    • account_holder_name, account_holder_type, account_type, address_city An identical inline object (16 fields) appears in 3 operations. Move it to `components.schemas` and $ref it, or the SDK generates 3 separate types.
    • additional_tos_acceptances, address, address_kana, address_kanji An identical inline object (29 fields) appears in 4 operations. Move it to `components.schemas` and $ref it, or the SDK generates 4 separate types.
    • amount, expand, metadata 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.
    • 15 more, not listed here.

    What this rule checks

  3. Generated public names do not collide2.0Clean594 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.5Clean594 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.0Clean594 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.00.6 lost299 of 594 operations

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

    • POST /v1/account_links `PostAccountLinks` reads better as `createPostAccountLinks` at the call site.
    • POST /v1/account_sessions `PostAccountSessions` reads better as `createPostAccountSessions` at the call site.
    • POST /v1/accounts `PostAccounts` reads better as `createPostAccounts` at the call site.
    • POST /v1/accounts/{account} `PostAccountsAccount` reads better as `createPostAccounts` at the call site.
    • POST /v1/accounts/{account}/bank_accounts `PostAccountsAccountBankAccounts` reads better as `createPostAccountsBank` at the call site.
    • 294 more, not listed here.

    What this rule checks

  7. Operations carry a summary or description1.00.2 lost5 of 594 operations

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

    • POST /v1/application_fees/{id}/refund `PostApplicationFeesIdRefund` has neither summary nor description, so its generated method ships without documentation.
    • POST /v1/charges/{charge}/dispute `PostChargesChargeDispute` has neither summary nor description, so its generated method ships without documentation.
    • POST /v1/charges/{charge}/dispute/close `PostChargesChargeDisputeClose` has neither summary nor description, so its generated method ships without documentation.
    • GET /v1/customers/{customer}/discount `GetCustomersCustomerDiscount` has neither summary nor description, so its generated method ships without documentation.
    • GET /v1/customers/{customer}/subscriptions/{subscription_exposed_id}/discount `GetCustomersCustomerSubscriptionsSubscriptionExposedIdDiscount` has neither summary nor description, so its generated method ships without documentation.

    What this rule checks

  8. Request bodies are documented1.00.6 lost290 of 594 operations

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

    • GET /v1/account `GetAccount` has an undocumented request body, so every generated parameter for it will be comment-free.
    • GET /v1/accounts `GetAccounts` has an undocumented request body, so every generated parameter for it will be comment-free.
    • DELETE /v1/accounts/{account} `DeleteAccountsAccount` has an undocumented request body, so every generated parameter for it will be comment-free.
    • GET /v1/accounts/{account} `GetAccountsAccount` has an undocumented request body, so every generated parameter for it will be comment-free.
    • DELETE /v1/accounts/{account}/bank_accounts/{id} `DeleteAccountsAccountBankAccountsId` has an undocumented request body, so every generated parameter for it will be comment-free.
    • 285 more, not listed here.

    What this rule checks

  9. Failure responses are declared1.0Clean594 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.01.0 lost594 of 594 operations

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

    • GET /v1/account `GetAccount` is untagged, so it lands in a namespace derived from its path.
    • POST /v1/account_links `PostAccountLinks` is untagged, so it lands in a namespace derived from its path.
    • POST /v1/account_sessions `PostAccountSessions` is untagged, so it lands in a namespace derived from its path.
    • GET /v1/accounts `GetAccounts` is untagged, so it lands in a namespace derived from its path.
    • POST /v1/accounts `PostAccounts` is untagged, so it lands in a namespace derived from its path.
    • 589 more, not listed here.

    What this rule checks

  11. No duplicate or equivalent paths1.0Clean419 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.57 lost415 of 594 operations

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

    • DELETE /v1/accounts/{account}#path:account `account` has no description, so the generated argument has no IDE guidance.
    • GET /v1/accounts/{account}#path:account `account` has no description, so the generated argument has no IDE guidance.
    • POST /v1/accounts/{account}#path:account `account` has no description, so the generated argument has no IDE guidance.
    • POST /v1/accounts/{account}/bank_accounts#path:account `account` has no description, so the generated argument has no IDE guidance.
    • DELETE /v1/accounts/{account}/bank_accounts/{id}#path:account `account` has no description, so the generated argument has no IDE guidance.
    • 410 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

Packaging, outside the score

This generates one package with 594 operations and 1454 models. Frontend consumers download all of it to call any of it, and low-spec machines pay for it in IDE and build time. The largest groups are `v1` (594), and each is a candidate for its own project.

What 6.6 means for an SDK

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

The client compiles and works. Callers will feel the soft spots: a few methods that return an untyped value, arguments with no hint on them, a namespace or two named after a path segment rather than a resource.

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

Clean

Successful responses declare a schema

594 operations clean

−0.5

Shared models live in components and are $ref'd

20 of 594 operations

Clean

Generated public names do not collide

594 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. Operations carry a summary or description

    Write one sentence of summary. It lands on the reference page and in the SDK's doc comment. Inside Octri this one has a one-click fix.

  4. Request bodies are documented

    Describe the body, or the fields inside it. Field-level prose is the one that reaches the SDK's arguments. Inside Octri this one has a one-click fix.

  5. Operations are tagged

    Tag every operation. Tags are what decide whether a caller writes `client.invoices.list()` or `client.misc.list()`. Inside Octri this one has a one-click fix.

  6. 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 Stripe API or Stripe Dev Platform Team.