Spec compatibility

typeship accepts Swagger 2.0, OpenAPI 3.0.x, and OpenAPI 3.1.x as JSON or YAML, up to 10MB, plus GraphQL schemas as SDL, introspection JSON, or an introspectable endpoint URL. The rule throughout: generation fails only for a document that is not a spec at all. Everything else generates, and anything skipped or approximated is reported as a warning on the result.

Swagger 2.0

2.0 documents are normalized to OpenAPI 3.0 before generation. The converter covers the constructs that appear in real specs:

• host, basePath, and schemes become the server URL. https is preferred when listed.
• definitions become components.schemas. $ref pointers are rewritten to their 3.0 locations.
• body parameters become request bodies. formData parameters become a form-encoded body, or multipart when there are file uploads.
• consumes and produces become content types on request and response bodies.
• securityDefinitions become security schemes. Basic, apiKey, and oauth2 are mapped. Unsupported types are skipped with a warning.

Known limitation: shared parameters in the top-level parameters section that are body or formData parameters cannot be converted in place and are skipped with a warning. Inline them in each operation for full fidelity.

References

Only local references (#/components/...) are resolved. External references to other files or URLs are not fetched. The referenced schema becomes unknown and a warning is reported. Dangling local references are treated the same way. Bundle multi-file specs into one document before generating.

GET and HEAD request bodies

Request bodies declared on GET or HEAD operations are dropped, with a warning listing the affected operations. Intermediaries do not reliably transmit GET bodies, so the SDK refuses to expose them.

Server URLs

• The first entry in servers becomes the client's default base URL. Server variables are substituted with their declared defaults.
• Two or more servers export named environments, taken from each server's description.
• A relative server URL (/v1) or a variable without a default cannot produce a usable base URL. The client is still generated, but the base URL becomes a required constructor option and a warning says so.

Authentication

When OAuth2 is declared, the generated CLI also gains a device-flow login once a client id is configured. See login, logout, whoami.

Webhooks

The webhooks section (3.1) and the x-webhooks convention (3.0) generate typed events and a verifying parser. Each webhook needs a JSON request body schema. See Webhooks.

Bodies and responses

Pagination

Four styles are detected from parameter and response names. When detection guesses wrong, pin the rule per operation. See Pagination and Pagination rules.

GraphQL

GraphQL schemas generate the same TypeScript package as OpenAPI specs, on the same runtime. Queries become methods on client.query, mutations on client.mutation. Object types carry an optional __typename literal. Unions, and interfaces with implementers, become a union of their concrete types, discriminated by __typename. Subscriptions are skipped with a warning. Custom scalars map to unknown. Operation documents are not an input. The endpoint and auth scheme, which a schema cannot declare, come from config and default to the URL the schema was fetched from and a bearer token. See Generate from GraphQL.

When generation fails

Hard failures are reserved for documents that are not a spec at all: empty input, unparseable JSON or YAML, a top level that is not an object, no openapi or swagger field, an unsupported version, no paths, no Query or Mutation fields, or more than 10MB. Errors and warnings lists every message with what to do about it.