This repository contains an OpenAPI specification for Stripe's API. Both JSON and YAML formats are included and available in the openapi directory.

The specification ships with a few vendor-specific fields to help represent information in ways that are difficult in OpenAPI by default.

Resources include an x-expandableFields that contains a list of fields that are expandable by making an API request with an expand parameter. See expanding objects.

For example:

definitions:
  ...
  charge:
    ...
    x-expandableFields:
    - balance_transaction

Any expandable field within a resource contains a set of references to the resources that it might be expanded to.

For example:

definitions:
  ...
  charge:
    properties:
      ...
      balance_transaction:
        description: ID of the balance transaction that describes the impact of this
          charge on your account balance (not including refunds or disputes).
        type:
        - string
        x-expansionResources:
          oneOf:
          - "$ref": "#/definitions/balance_transaction"

Some API responses are "polymorphic" in that they might return multiple types of resources which is a case that OpenAPI can't handle. In these cases the spec will reference a "synthetic" resource which is an aggregate of the properties common to all the possible resources. It will also include the field x-polymorphicResources which references those resources more precisely.

For example:

definitions:
  ...
  external_account_source:
    properties:
      ...
    x-polymorphicResources:
      oneOf:
      - "$ref": "#/definitions/bank_account"
      - "$ref": "#/definitions/card"

Resources include x-resourceId which is a canonical name for each resource. It can be used in conjunction with the files openapi/fixtures.{json,yaml} to look up a sample representation (otherwise known as a "fixture") of the resource.

For example:

# spec.yaml
---
definitions:
  ...
  charge:
    ...
    x-resourceId: charge

# fixtures.yaml
---
invoice_line_item:
  ...

Please make updates to the script included in bin to help maintain consistency and commit cleanliness (search JIRA for full instructions):

bin/update

Run the test suite:

make