0.11.5 • Public • Published

Travis (.org) npm Join the chat at https://gitter.im/oasgraph/Lobby


Generates a GraphQL schema for a given OpenAPI Specification (OAS).

Overview of translation

Note: To use OASGraph via the command line, refer to the oasgraph-cli package.


OASGraph can be installed using:

npm i oasgraph

Note that GraphQL.js is a peer dependency of OASGraph and must be installed separately (e.g., using npm i graphql).


The basic way to use OASGraph is to pass an OpenAPI Specification (OAS; version 2.0 or 3.0.x) to the generateGraphQLSchema function. The function returns a promise that resolves on an object containing the generated GraphQL schema as well as a report about possible issues when generating the schema:

const { createGraphQlSchema } = require('oasgraph')
// load or construct OAS (const oas = ...)
const { schema, report } = await createGraphQlSchema(oas)

Example of Serving the Generated GraphQL Schema

The schema generated by OASGraph can, for example, be served using Express.js and the GraphQL HTTP Server Middleware:

const express = require('express')
const graphqlHTTP = require('express-graphql')
const OASGraph = require('oasgraph')

async function main (oas) {
  // generate schema:
  const {schema, report} = await createGraphQLSchema(oas)

  // server schema:
  const app = express()
  app.use('/graphql', graphqlHTTP({
    graphiql: true

main(oas) // oas loaded / constructed someplace else


The createGraphQlSchema function takes an optional options object as a second argument:

createGraphQLSchema(oas, [options])

The options object can contain the following properties:

  • strict (type: boolean, default: false): OASGraph generally tries to produce a working GraphQL schema for a given OAS if the strict mode is disabled. If OASGraph cannot fully translate a given OAS (e.g., because data schema definitions are incomplete or there are name collusions that cannot be resolved), createGraphQLSchema will per default degrade gracefully and produce a partial GraphQL schema. OASGraph will log warnings (given logging is enabled). If the strict mode is enabled, however, createGraphQLSchema will throw an error if it cannot create a GraphQL schema matching the given OAS perfectly.

  • headers (type: object, default: {}): Headers to be sent in every request to the API described by the given OAS. Parameters defined in the OpenAPI Specification to set these headers will be ignored by OASGraph.

  • qs (type: object, default: {}): Query parameters to be sent in every request to the API described by the given OAS. Parameters defined in the OpenAPI Specification to set these query parameters will be ignored by OASGraph.

  • viewer (type: boolean, default: true): The viewer object types (i.e. QueryViewer and MutationViewer) are artificial constructs that allow users to pass authentication credentials to OASGraph. Unfortunately, they are bulky and do not provide an accurate representation of the API. Depending on the API, it may be possible to send all credentials through the header option, so this option allows to disable OASGraph-generated viewer object types.

  • tokenJSONpath (type: string, default: undefined): Used to pass the JSONPath of the OAuth token in the GraphQL context. To see more details, click here.

  • addSubOperations (type: boolean, default: false): When true, OASGraph will nest GET operations based on their path hierarchy in the given OAS. E.g., when the OAS contains two paths /users/{id} and /users/{id}/friends, OASGraph will make friends queryable from within user. Note: This may cause problems when resolving GraphQL types in certain contexts, where the required variables are not available.

Consider this example of passing options:

OASGraph.createGraphQLSchema(oas, {
  headers: {
    authorization: 'asfl3032lkj2' // send authorization header in every request
    'x-origin': 'GraphQL' // send header to identify requests made via GraphQL
  qs: {
    limit: 30 // send limit query string in every request
  addSubOperations: false


Per default, OASGraph will wrap API requests that need authentication in corresponding viewers, which allow the user to pass required credentials. OASGraph currently supports viewers for basic authentication and API keys. For example, a query using an API key viewer is:

  viewerApiKey (apiKey: "api_key_here") {
    ...  // query for authenticated data here

OASGraph uses dedicated viewers for mutations. For example, a mutation using a basic authentication viewer is:

mutation {
  mutationViewerBasic (username: "user", password: "secret") {
    ...  // mutate authenticated data here

OASGraph further provides anyAuth viewers (for queries and mutations), which allow the user to simultaneously provide information for multiple authentication mechanisms. AnyAuth viewers allow OASGraph to resolve nested queries and mutations that encompass API requests with different authentication mechanisms. For example, consider the following query:

  viewerAnyAuth (
    exampleApiKeyProtocol: {apiKey: "a1p2i3k4e5y"}
    exampleBasicProtocol: {
      username: "erik"
      password: "secret"
  ) {
    patentWithId (patentId: "test") {  // requires "exampleApiKeyProtocol"
      inventor {                       // requires "exampleBasicProtocol"


Because OASGraph is a library, it cannot make the callbacks that OAuth requires by itself. Instead, the user must take care of the callback. After the user has obtained the OAuth token from the callback, simply pass the token, specifically the path of the token, to OASGraph through the tokenJSONpath option.

To see an example of how this would work, click here!


OASGraph provides multiple levels of logging, which can be controlled by a DEBUG environment variable. You can enable these levels using:

DEBUG=level_1,level_2 node app-using-oasgraph.js

The following logging levels are supported:

  • preprocessing: Logs information about preprocessing the OAS to GraphQL.
  • translation: Logs information about translating an OAS to GraphQL.
  • http: Logs information about the HTTP requests made to the API.


To test OASGraph, run:

npm test

This command will temporarily start and later shut down an example REST(-like) API.



Package Sidebar


npm i @xanthous/oasgraph

Weekly Downloads






Unpacked Size

6.61 MB

Total Files


Last publish


  • harchiko
  • lhr0909
  • necmttn
  • osmanmesutozcan