No native modules, iOS pod installs, or Android linking steps are required. This is a pure Node.js library.

Project setup

1. Copy the source/ directory into your project, e.g. src/openapi-to-graphql/.

2. Update tsconfig.json to include the source in compilation and enable required options:

   {
     "compilerOptions": {
       "target": "ES2019",
       "module": "commonjs",
       "esModuleInterop": true,
       "resolveJsonModule": true,
       "skipLibCheck": true,
       "strict": true,
       "paths": {
         "openapi-to-graphql": ["./src/openapi-to-graphql/index.ts"]
       }
     },
     "include": ["src/**/*"]
   }
   

3. If you use ESM ("module": "ESNext"), ensure your bundler resolves the cross-fetch and form-data CJS modules correctly, or add them to esmExternals.

4. No environment variables are required by the library itself. API base URLs are read from the OAS servers field; you can override them via the baseUrl option at runtime.

5. For subscriptions, ensure a PubSub-compatible broker is reachable and configure the mqtt or webSocket callback options when calling createGraphQLSchema.

Public API

createGraphQLSchema

import { createGraphQLSchema } from './openapi-to-graphql/index'
import { Oas3 } from './openapi-to-graphql/types/oas3'
import { Options } from './openapi-to-graphql/types/options'

async function createGraphQLSchema<TSource = any, TContext = any, TArgs = any>(
  spec: Oas3 | Oas2 | (Oas3 | Oas2)[],
  options?: Options<TSource, TContext, TArgs>
): Promise<{ schema: GraphQLSchema; report: Report }>

The primary entry point. Pass one or more OAS/Swagger documents and receive a fully constructed GraphQLSchema plus a report summarising warnings and which operations were translated. Use this whenever you want to mount an OAS-backed GraphQL endpoint.

Options / InternalOptions

import { Options } from './openapi-to-graphql/types/options'

type Options<TSource, TContext, TArgs> = {
  baseUrl?: string
  requestOptions?: RequestOptions
  connectOptions?: ConnectOptions
  viewer?: boolean
  headers?: { [key: string]: string }
  qs?: { [key: string]: string }
  customResolvers?: { [path: string]: { [method: string]: GraphQLFieldResolver<TSource, TContext, TArgs> } }
  // ...and more
}

Controls every aspect of schema generation: base URL overrides, custom resolvers, authentication viewer injection, request-level headers, and query-string defaults. Pass this as the second argument to createGraphQLSchema.

Report

import { Report } from './openapi-to-graphql/types/options'

type Report = {
  warnings: string[]
  numOps: number
  numOpsQuery: number
  numOpsMutation: number
  numOpsSubscription: number
  numQueriesCreated: number
  numMutationsCreated: number
  numSubscriptionsCreated: number
}

Returned alongside the schema from createGraphQLSchema. Inspect report.warnings to surface OAS incompatibilities at startup, and use the operation counts to verify your spec was fully consumed.

Working examples

Scenario - Basic schema generation from a local OAS file

Load a JSON OpenAPI spec from disk, generate a GraphQL schema, and execute a query.

import { createGraphQLSchema } from './openapi-to-graphql/index'
import { graphql } from 'graphql'
import * as fs from 'fs'

async function main() {
  const oas = JSON.parse(fs.readFileSync('./petstore.json', 'utf-8'))

  const { schema, report } = await createGraphQLSchema(oas, {
    baseUrl: 'https://petstore.swagger.io/v2'
  })

  console.log('Warnings:', report.warnings)
  console.log('Queries created:', report.numQueriesCreated)

  const result = await graphql({
    schema,
    source: '{ pets { id name } }'
  })
  console.log(JSON.stringify(result, null, 2))
}

main().catch(console.error)

Scenario - Express + graphql-http server with authentication viewer

Wrap an API that uses API-key auth and mount it behind an Express GraphQL endpoint.

import express from 'express'
import { createHandler } from 'graphql-http/lib/use/express'
import { createGraphQLSchema } from './openapi-to-graphql/index'
import fetch from 'cross-fetch'

async function startServer() {
  const oas = await fetch('https://example.com/api/openapi.json').then(r => r.json())

  const { schema, report } = await createGraphQLSchema(oas, {
    viewer: true,          // injects QueryViewer / MutationViewer auth wrappers
    baseUrl: 'https://example.com/api'
  })

  if (report.warnings.length) {
    console.warn('OAS warnings:', report.warnings)
  }

  const app = express()
  app.use('/graphql', createHandler({ schema }))
  app.listen(4000, () => console.log('GraphQL at http://localhost:4000/graphql'))
}

startServer()

Scenario - Multiple OAS documents merged into one schema

Combine two separate service specs into a single unified GraphQL schema.

import { createGraphQLSchema } from './openapi-to-graphql/index'
import { Oas3 } from './openapi-to-graphql/types/oas3'
import { graphql } from 'graphql'

async function mergedSchema() {
  const [usersSpec, ordersSpec]: Oas3[] = await Promise.all([
    fetch('/specs/users.json').then(r => r.json()),
    fetch('/specs/orders.json').then(r => r.json())
  ])

  const { schema, report } = await createGraphQLSchema([usersSpec, ordersSpec], {
    headers: { 'X-Internal-Token': process.env.INTERNAL_TOKEN ?? '' }
  })

  console.log(`Total operations: ${report.numOps}`)

  const result = await graphql({
    schema,
    source: '{ user(id: "1") { name } order(id: "42") { total } }'
  })
  return result
}

File walkthrough

• index.ts - Exports createGraphQLSchema; orchestrates preprocessing, schema building, and auth wiring.
• preprocessor.ts - Iterates OAS paths/operations, resolves $ref pointers, and produces typed Operation and DataDefinition objects consumed by the builders.
• oas_3_tools.ts - Stateless helpers for resolving references, normalising server URLs, extracting request/response schemas, and converting Swagger 2 to OAS 3 via swagger2openapi.
• schema_builder.ts - Maps JSON Schema primitives and objects to GraphQLObjectType, GraphQLInputObjectType, GraphQLEnumType, GraphQLUnionType, and scalars; calls resolver_builder to attach resolvers.
• resolver_builder.ts - Produces GraphQLFieldResolver closures that build HTTP requests, handle auth injection, process file uploads, and manage PubSub for subscriptions.
• auth_builder.ts - Generates intermediate QueryViewer/MutationViewer object types that accept security credentials and forward them via the _openAPIToGraphQL object.
• graphql_tools.ts - Miscellaneous GraphQL utility functions used across builders.
• utils.ts - handleWarning, MitigationTypes, getCommonPropertyNames, and string sanitization helpers.
• types/ - Pure TypeScript interfaces; no runtime code. Covers OAS2, OAS3, options, operations, preprocessing data, and GraphQL-specific types.

Common pitfalls and fixes

• $ref resolution fails at runtime: Ensure the full OAS document (not just a fragment) is passed; oas_3_tools.ts resolves references internally against the root object.
• swagger2openapi conversion errors on Swagger 2 specs: Install swagger2openapi at exactly the version pinned in the upstream package.json; API surface breaks across major versions.
• ESM/CJS interop with cross-fetch or form-data: Add "esModuleInterop": true in tsconfig.json and import as import crossFetch from 'cross-fetch', not as a namespace import.
• Duplicate GraphQL type names crash schema build: Two OAS schemas with the same title field produce colliding type names; use x-openapi-to-graphql-name extension on conflicting schemas to force unique names.
• Authentication credentials not forwarded to nested resolvers: OpenAPI-to-GraphQL passes auth via the _openAPIToGraphQL object on each resolver result, not via GraphQL context; do not strip unknown fields from resolver return values.
• Subscriptions silently produce no events: The PubSub instance in resolver_builder.ts is module-scoped; your MQTT/WebSocket bridge must publish to the same in-process PubSub topic name, or replace the internal pubsub instance with a shared one via a custom resolver.

Vibe-coding prompt template

I am integrating the openapi-to-graphql library (source in `src/openapi-to-graphql/`)
into my existing Node.js/TypeScript/Express project. The USAGE.md at the root of
this block is the authoritative reference for all real exports, file locations,
and working code examples.

Please help me do the following step-by-step:

1. Confirm that all required npm dependencies listed in USAGE.md ## Required dependencies
   are present in my package.json and install any that are missing.

2. Update my tsconfig.json to match the settings in USAGE.md ## Project setup,
   preserving my existing options where possible.

3. Create a new file `src/graphql/schema.ts` that imports `createGraphQLSchema`
   from `src/openapi-to-graphql/index`, loads my OAS spec from `openapi.json`,
   and exports the resulting `GraphQLSchema`.

4. Wire the schema into my existing Express app using `graphql-http`,
   following the pattern in USAGE.md ## Working examples - Scenario Express server.

5. Log any `report.warnings` at startup so OAS incompatibilities are visible.

6. If my spec uses API-key authentication, enable the `viewer: true` option
   as described in USAGE.md ## Public API - Options.

Only use symbols and imports that appear in USAGE.md. Do not invent new APIs.
The upstream package name is `openapi-to-graphql` (ibm_openapi_to_graphql).

License and credit

The source is licensed under the MIT License (stated in every source file header: https://opensource.org/licenses/MIT). Copyright IBM Corp. 2018.

Upstream repository: ibm/openapi-to-graphql — package openapi-to-graphql on npm. Note that active development has moved to GraphQL Mesh's OpenAPI handler, which is a maintained fork.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。