OpenAPI-to-GraphQL

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

Note: To use OpenAPI-to-GraphQL via the command line, refer to the openapi-to-graphql-cli package.

Installation

OpenAPI-to-GraphQL can be installed using:

npm i openapi-to-graphql

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

Usage

The basic way to use OpenAPI-to-GraphQL 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('openapi-to-graphql')
// load or construct OAS (const oas = ...)
const { schema, report } = await createGraphQLSchema(oas)

OpenAPI-to-GraphQL can also create GraphQL interfaces from multiple APIs. To do so, simply provide multiple OpenAPI Specifications.

const { schema, report } = await createGraphQLSchema([oas, oas2, oas3]])

Example of Serving the Generated GraphQL Schema

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

const express = require('express')
const { graphqlHTTP } = require('express-graphql')
const { createGraphQLSchema } = require('openapi-to-graphql')

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

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

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

Nested Objects

To create nested object types you need to define link objects in the OAS. According to the specification, a link object "represents a possible design-time link for a response." In other words, a link object describes how the data from one operation can be used to query another.

For example, let's say we have an API that has an operation called GET /users/{userId} and an operation called GET /employers/{employerId}. In addition, let's say that the user object returned from GET /users/{userId} contains a field called currentEmployerId. We can define a link object that says, use the currentEmployerId returned by GET /users/{userId} to query GET /employers/{employerId} in order to get the user's current employer. That link would look like the following:

{
  "operationId": "employer",
  "parameters": {
    "employerId": "$response.body#/currentEmployerId"
  }
}

If you define a link object, then OpenAPI-to-GraphQL will add a new field to your object type. In this case, the User object type will have not only an currentEmployerId field, but also an employer field. Then, you will be able to create nested GraphQL queries like the following:

query {
  user(userId: "Alan") {
    currentEmployerId
    employer {
      name
    }
  }
}

To create nested object types for arrays, you will need to keep the following in mind.

Continuing from the previous example, let's say that there is a third operation called GET /friends/{userId} which would return an array of users, specifically the friends of a particular user. Furthermore, let's say you wanted to run the following query, which would allow you to get all the employers of Alan's friends:

query {
  friends(userId: "Alan") {
    currentEmployerId
    employer {
      name
    }
  }
}

If this was like the previous case, you would simply define a link from GET /friends/{userId} to GET /employers/{employerId}. However, this is impossible because of the current specification. This is because this operation returns an array rather than an object and the current specification does not provide a way to access individual elements of an array.

Nevertheless, OpenAPI-to-GraphQL can still create a nested relationship. This is because OpenAPI-to-GraphQL reuses object types. If GET /friends/{userId} returns an array of User object types, then each of those users will take on the links defined in other operations that return User object types. In other words, because GET /friends/{userId} returns an array of User object types and GET /users/{userId}, which also returns a User object type, has a link to GET /employers/{employerId}, you will still be able to get all the employers of a user's friends because of the shared type.

OpenAPI-to-GraphQL can create GraphQL interfaces from multiple OASs. To create link between OASs, you will need use an operationRef instead of operationId. You will also need to create references using the title of the OAS. Although this is not supported by the specification, it is necessary for this functionality to work.

For example, let's say that there was a library API that would allow you to get a user's favorite books by querying GET /favoriteBooks/{name}. In addition, let's say that in the original API, the User object type contained two fields, firstName and lastName. To create a link between the original API and the library API, you would have to write something like the following:

{
  "operationRef": "I <3 Books API#/paths/~1favoriteBooks~1{name}/get",
  "parameters": {
    "name": "{$response.body#/firstName} {$response.body#/lastName}"
  }
}

Notice that the slashes in the path /favoriteBooks/{name} must be escaped with ~1 and that you can compose parameter values with different runtime expressions using brackets.

File Uploads

Support for file uploads through GraphQL is implemented based on the spec defined here, through the module graphql-upload. To opt in for file uploads, a GraphQL client that provides support for the spec must be used. Additionally, on the GraphQL server, the util method processRequest provided by the module graphql-upload must be integrated to format the received request body to match the expectations for the spec.

Options

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): OpenAPI-to-GraphQL generally tries to produce a working GraphQL schema for a given OAS if the strict mode is disabled. If OpenAPI-to-GraphQL 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 by default degrade gracefully and produce a partial GraphQL schema. OpenAPI-to-GraphQL 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.

Schema options:

• operationIdFieldNames (type: boolean, default: false): By default, query field names are based on the return type's type name and mutation field names are based on the operationId, which may be generated if it does not exist. This option forces OpenAPI-to-GraphQL to only create field names based on the operationId.

• fillEmptyResponses (type: boolean, default: false): OpenAPI-to-GraphQL, by default, will only wrap operations that have a response schema. Therefore, operations that do not have response schemas will be ignored. The reason is that all GraphQL objects must have a data structure and in these cases where the OAS does not define response schemas, the data structures cannot be safely assumed. As a result, it is recommended that the OAS should be modified to include a response schema. However, under certain circumstances, some operations should not in fact have a response schema. One circumstance is HTTP status code 204, in which no content should be returned. The option fillEmptyResponses will allow OpenAPI-to-GraphQL to wrap these operations by assigning these operations a placeholder data structure. Although this data structure is meaningless, the operation will appear in the schema.

• addLimitArgument (type: boolean, default: false): Add a limit argument to fields returning lists of objects/lists that will limit the number of returned elements, selecting the first n elements of the list.

• idFormats (type: string[], default: []): If a schema is of type string and has format UUID, it will be translated into a GraphQL ID type. To allow for more customzation, this option allows users to specify other formats that should be interpreted as ID types.

• selectQueryOrMutationField (type: object, default: {}): OpenAPI-to-GraphQL, by default, will make all GET operations into Query fields and all other operations into Mutation fields. This option allows users to manually override this process. The operation is identifed first by the title of the OAS, then the path of the operation, and lastly the method of the operation. The selectQueryOrMutationField object is thus a triply nested object where the outer key is the title, followed by the path, and finally the method, which points to an integer value of either 0, or 1, corresponding to Query or Mutation type respectively.

• genericPayloadArgName (type: boolean, default: false): Set the default argument name for the payload of a mutation to requestBody. Otherwise, the name will default to the camelCased pathname.

• simpleNames (type: boolean, default: false): By default, field names are sanitized to conform with GraphQL conventions, i.e. types should be in PascalCase, fields should be in camelCase, and enum values should be in ALL_CAPS. This option will prevent OpenAPI-to-GraphQL from enforcing camelCase field names and PascalCase type names, only removing illegal characters and staying as true to the provided names in the OAS as possible.

• simpleEnumValues (type: boolean, default: false): By default, field names are sanitized to conform with GraphQL conventions, i.e. types should be in PascalCase, fields should be in camelCase, and enum values should be in ALL_CAPS. This option will prevent OpenAPI-to-GraphQL from enforcing ALL_CAPS enum values, only removing illegal characters and staying as true to the provided enum values in the OAS as possible.

• singularNames (type: boolean, default: false): Experimental feature that will try to create more meaningful names from the operation path than the response object by leveraging common conventions. For example, given the operation GET /users/{userId}/car, OpenAPI-to-GraphQL will create a Query field userCar. Note that because users is followed by the parameter userId, it insinuates that this operation will get the car that belongs to a singular user. Hence, the name userCar is more fitting than usersCar so the pluralizing 's' is dropped. This option will also consider irregular plural forms.

• createSubscriptionsFromCallbacks (type: boolean, default: false): Generates subscription fields from callback objects. The keys (runtime expressions) of the callback objects will be interpolated as the topic of a publish/subscription connection using graphql-subscriptions. Read the doc for explanations and examples regarding its usage.

Resolver options:

• headers (type: object | function, default: {}): Headers to be sent in every request to the API. Parameters defined in the OpenAPI Specification and set by these headers will be ignored by OpenAPI-to-GraphQL. If used as a function, the following parameters will be exposed per-request: the operation's method, the operation's path, the API title, and resolverParams (the GraphQL resolver's parameters). The function should return the desired headers.

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

• requestOptions (type: object, default: {}): Additional options, provided by the Request module, that can be used to configure the HTTP calls that powers the generated GraphQL resolvers. A common use case for this option is to set up a web proxy with the proxy field. Parameters defined in the OpenAPI Specification and set by this option will be ignored by OpenAPI-to-GraphQL. Additionally, the headers field has the feature of being used as a function. If used as a function, the following parameters will be exposed per-request: the operation's method, the operation's path, the API title, and resolverParams (the GraphQL resolver's parameters). The function should return the desired headers.

• baseUrl (type: string): Used to manually specify the base URL which all paths will be built on. Normally, OpenAPI-to-GraphQL will select a base URL from the server object defined in the OAS. However, if the server object contains multiple URLs, OpenAPI-to-GraphQL will randomly select one. The purpose of this option is to provide greater control over the base URL in these situations, especially when the OAS cannot be modified. This option may also prove to be useful in testing and development.

• customResolvers (type: object, default: {}): OpenAPI-to-GraphQL, by default, creates resolver functions that make REST calls to resolve Query and Mutation fields in the generated GraphQL interface. This option allows users to provide custom resolver functions to be used in place of said ones created by OpenAPI-to-GraphQL. The field that the custom resolver will affect is identifed first by the title of the OAS, then the path of the operation, and lastly the method of the operation. The customResolvers object is thus a triply nested object where the outer key is the title, followed by the path, and finally the method, which points to the resolver function itself. The resolver function can use the parameters obj, args, context, and info in order to produce the proper data, as do standard resolver functions in GraphQL. Use cases include the resolution of complex relationships between types, implementing performance improvements like caching, or dealing with non-standard authentication requirements. Note: Because the arguments are provided by the GraphQL interface, they may look different from the parameters defined by the OAS. For example, they will have sanitized names. The request body will also be contained in the arguments as an input object type.

• customSubscriptionResolvers (type: object, default: {}): If the createSubscriptionsFromCallbacks is enabled, OpenAPI-to-GraphQL will generate Subscription fields. This option allows users to provide custom resolver and subscribe functions to be used in place of said ones created by OpenAPI-to-GraphQL. The field that the custom resolver and subscribe functions will affect is identifed first by the title of the OAS, then the path of the operation, and lastly the method of the operation. The resolver is provided via the resolver field and the publish function is provided via the publish field. The customSubscriptionResolvers object is thus a quadruply nested object where the outer key is the title, followed by the path, then the method, and lastly either resolver or publish which points to the resolver function itself or publish function. See the Subscriptions tutorial for more information. Note: Because the arguments are provided by the GraphQL interface, they may look different from the parameters defined by the OAS. For example, they will have sanitized names. The request body will also be contained in the arguments as an input object type.

• fileUploadOptions (type: object, default: {}): This options allows users to provide custom options for the form data object that will be used to process requests to endpoints that require a multipart request body, provided through the form-data module. See file uploads.

Authentication options:

• 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 OpenAPI-to-GraphQL. They are created when the OAS defines security scheme objects and when operations adopt them through a security requirement object. A viewer is created for each security scheme and each viewer contains authenticated operations that uses its respective security scheme. In addition, a special anyAuth viewer, which can authenticate requests utilizing different security schemes, is created. Unfortunately, viewers are bulky so, depending on the API, it may be possible to send credentials through the header, qs, or requestOptions options. Note: OAuth authentication is handled using the tokenJSONpath and sendOAuthTokenInQuery options.

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

• sendOAuthTokenInQuery (type: boolean, default: false): If set to true, the OAuth token extracted from the provided tokenJSONpath will be sent as an access_token query parameter (instead of in the header).

Validation options:

• oasValidatorOptions (type: object, default: {}): We use the oas-validator library to validate Swaggers/OASs. We expose the options so that users can have more control over validation. See here for more information.

• swagger2OpenAPIOptions (type: object, default: {}): We use the swagger2openapi library to validate Swaggers/OASs. We expose the options so that users can have more control over validation. See here for more information.

Logging options:

• provideErrorExtensions (type: boolean, default: true): If a query cannot be fulfilled, GraphQL returns a list of error objects for all fields that could not be resolved. OpenAPI-to-GraphQL will add an extensions object to all error objects resulting from REST calls that did not return successful HTTP codes (i.e. 200-299). Each extensions object contains data about the REST call (e.g. the method, path, status code, response headers, and response body). This data can be useful for debugging but it can also unintentionally leak information. If set to false, this option prevents the extensions objects from being created.

• equivalentToMessages (type: boolean, default: true): Append a small message to the description of a field that clarifies the operation the field will trigger. The message will take the form of Equivalent to {title of OAS} {method in ALL_CAPS} {path} (the title will only appear if multiple OASs are provided). Messages will appear for query/mutation fields as well as for fields created by links. Note: These messages may unintentionally leak information about the underlying REST API.

Consider this example of passing options:

OpenAPI-to-GraphQL.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
  },
  requestOptions: {
    proxy: "https://my-proxy:3128"
  },
  customResolvers: {
    'I <3 Books API': {
      '/favoriteBooks/{name}': {
        'get': (obj, args, context, info) => {
          return {
            books: [
              'A Guide to OpenAPI-to-GraphQL',
              'Why OpenAPI-to-GraphQL is Amazing',
              'Long Live OpenAPI-to-GraphQL!'
            ]
          }
        }
      }
    }
  }
})

Custom Type and Field Names and Enum Values

The x-graphql-type-name, x-graphql-field-name, and x-graphql-enum-mapping OAS extensions can be used to configure type and field names as well as enum values.

The type and field names and enum values that OpenAPI-to-GraphQL generates may not be adequate or may not be consistent over different versions so this is a way to guarantee consistency.

x-graphql-type-name and x-graphql-field-name can be added to a JSON schema to change the type name as well as change a field name. OpenAPI-to-GraphQL will also use x-graphql-type-name to name input object types by appending Input to the end of the name.

{
  "type": "object",
+ "x-graphql-type-name": "Response",
  "properties": {
    "code": {
      "type": "integer",
+     "x-graphql-field-name": "statusCode",
    }
  }
}

x-graphql-field-name can be added to an operation object to change a field name under the top-level Query, Mutation, and Subscription types.

{
  "/pet/findByStatus": {
    "get": {
+     "x-graphql-field-name": "getPetsByStatus",
      "parameters": [
        ...
      ],
      "responses": {
        ...
      }
    }
  }
}

x-graphql-field-name can be added to a link object to change the name of a linked field (see section on Nested Objects).

{
+ "x-graphql-field-name": "orderPet",
  "operationId": "getPetById",
  "parameters": {
    "petId": "$response.body.petId"
  },
  "description": "Link from Order to Pet"
}

x-graphql-enum-mapping can be added to a JSON schema to change the enum values. It is a mapping from the original enum values to the ones that should used in the GraphQL interface.

{
  "type": "string",
  "enum": ["available", "pending", "sold"],
+ "x-graphql-enum-mapping": {
+   "available": "INITIAL",
+   "pending": "IN_PROGRESS",
+   "sold": "SOLD"
+ }
}

Authentication

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

{
  viewerBasicAuth (username: "user", password: "secret") {
    ...  // query for authenticated data here
  }
}

{
  viewerBearerAuth (token: "bearer_token_here") {
    ...  // query for authenticated data here
  }
}

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

OpenAPI-to-GraphQL 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
  }
}

OpenAPI-to-GraphQL further provides anyAuth viewers (for queries and mutations), which allow the user to simultaneously provide information for multiple authentication mechanisms. anyAuth viewers allow OpenAPI-to-GraphQL 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"
    }
  ) {
    patent (patentId: "test") {  // requires "exampleApiKeyProtocol"
      patentId
      inventor {                 // requires "exampleBasicProtocol"
        name
      }
    }
  }
}

Authorization

Because OpenAPI-to-GraphQL 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 OpenAPI-to-GraphQL through the tokenJSONpath option.

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

Logging

OpenAPI-to-GraphQL 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-openapi-to-graphql.js

The following logging levels are supported:

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

Testing

To test OpenAPI-to-GraphQL, run:

npm test

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

License

MIT