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

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 3

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 4

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

Swagger-to-GraphQL converts your existing Swagger schema to an executable GraphQL schema where resolvers perform HTTP calls to certain real endpoints. It allows you to move your API to GraphQL with nearly zero effort and maintain both REST and GraphQL APIs. Our CLI tool also allows you get the GraphQL schema in Schema Definition Language.