How to document GraphQL with Swagger \ OpenAPI?

Question

How to document GraphQL with Swagger? We have a huge backend REST API which is recently has partially started to use GraphQL. For documenting API we're using Swagger.

The question is: how to use Swagger(OpenAPI) for documenting GraphQL endpoints? There's absolutely no related info in official docs of Swagger or GraphQL.

Answer 1

GraphQL APIs are usually documented through the documentation facilities provided by the GraphQL server itself: The type system and the descriptions on the types and fields. A tool like GraphQL playground lets you explore the API documentation through clicking/searching in a visual document tree or through IDE like features (autocomplete + tooltips). This is mostly how companies expose their public GraphQL APIs. Some companies also expose swagger like documentation (e.g. Github v4 API docs). This tool can create such a documentation for your API.

Swagger on the other hand solves this problem for REST APIs. As such Swagger is build for a different ecosystem. Swagger adds functionality to REST that works out of the box in GraphQL. So as far as I know there are no attempts from either side to create compatibility. There are some tools to expose Swagger/OpenAPI REST endpoints as GraphQL queries, which can be interesting for your transition period.

Answer 2

I just had the same requirement. What I basically did is I described the GraphQL as if it was a REST API - well basically it is: it is a HTTP endpoint, it uses the POST method, it posts json data in the body and it receives json as an answer.

I found out that it is not possible to document all the queries in swagger but it is possible to such a degree so that it is usable.

Here is the swagger yaml that I created:

swagger: "2.0"
info:
  description: "Graphql swagger"
  version: "1.0.0"
  title: "Graphql swagger"
host: "my-graphql-host.com"
basePath: "/"
schemes:
- "https"
paths:
  /api:
    post:
      summary: "GraphQL"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      responses:
        "200":
          description: "successful operation"
          schema:
            $ref: "#/definitions/GraphQLResponse"
      parameters:
        - in: body
          name: body
          description: "GraphQL query"
          required: true
          schema:
            $ref: "#/definitions/GraphQLQuery"
definitions:
  GraphQLQuery:
    type: "object"
    properties:
      query:
        type: "string"
  GraphQLResponse:
    type: "object"
    properties:
      data:
        type: "object"

This is how the preview of this swagger documentation looks like:

As you can see it only describes that a query is accepted but it does not describe which queries.

So to execute a query you need to transform it to string and pass it to the body. That means, the following query:

query {
  searchProducts(term: "MySearchTerm", language: EN) {
    hits {
      source {
        id
        Name
        Number
      }
    }
  }
}

needs to be transformed to

{
    "query": "query {  searchProducts(term: \"MySearchTerm\", language: EN) {    hits {      source {        id        Name        Number      }    }  }}"
}

Answer 3

Unfortunately, as of May 2021 there is no standard way to show GraphQL endpoint or link to GraphiQL UI from Swagger-UI.

Because GraphQL is competing with REST, most GraphQL vendors want developers to replace REST with GraphQL, not just use GraphQL for (read-only) queries.

Hopefully, when GraphQL more wider adopted and its advantages and disadvantages are better understood, a more balanced view would be to use better parts from both of them.

Answer 4

OpenAPI-to-GraphQL Translate APIs described by OpenAPI Specifications (OAS) or Swagger into GraphQL.

OpenAPI-to-GraphQL can be used in two ways:

CLI

The Command Line Interface (CLI) provides a convenient way to start a GraphQL server wrapping an API for a given OpenAPI Specification:

Install the OpenAPI-to-GraphQL CLI using:

npm i -g openapi-to-graphql-cli

Then, run the OpenAPI-to-GraphQL command and point it to an OpenAPI Specification:

openapi-to-graphql [options]

For further details, refer to the openapi-to-graphql-cli documentation.

Library

Use OpenAPI-to-GraphQL as a library in your application to generate GraphQL schemas.

Install OpenAPI-to-GraphQL as a dependency:

npm i -s openapi-to-graphql

Require OpenAPI-to-GraphQL and use the createGraphQLSchema function:
const { createGraphQLSchema } = require("openapi-to-graphql");
// load or construct OAS (const oas = ...)
const { schema, report } = await createGraphQLSchema(oas);

For further details, refer to the openapi-to-graphql-cli documentation.