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.

Solution 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.

Solution 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.

Solution 3

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.

Solution 4

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      }    }  }}"
}

View more solutions

Comments

[Helen]

Related (or duplicate): Document a GraphQL API, Best approach to implement swagger in GraphQL application

[Antares42]

Does this answer your question? Document a GraphQL API

[user12367662]

You seem to have misunderstood the question. Or maybe I do not understand something. A simple example from life: there is a frontend developer for whom I made a backend in GraphQL. How can this developer understand how to use this API? In the case of REST I can just send him to the generated Swagger page, but what can I do with GraphQL? What do I tell the frontend developer? Do I have to tell him in words? Or does he have to go through the backend code to understand how it works? Please explain.

[Herku]

You send him the URL to your GraphQL API. So let's say it is https://my.api.com/graphql. Now they can use their desktop application "GraphQL Playground" (which I linked) to simply put this URL in it and start exploring the API documentation. GraphQL is self documenting, meaning by building the server and adding description to the fields, a GraphQL client can make a meta query, to get all the info about how the API works.

[Herku]

You can do this yourself and go to graphql.org/swapi-graphql and click the "docs" link on the right side. This just works out of the box, completely for free. You can also serve this graphiql or playground from your server. Apollo Server even has this built in and will respond to all requests with the "Accept" header text/html the playground instead of an API response.

[user12367662]

GraphQL Playground is broken: github.com/prisma-labs/graphql-playground/issues/877

[Herku]

I am using Playground every day as an app on my MacBook as well as served from the browser. The issue does not seem to be related to a an issue with Playground and rather a collection of user related problems. But this does not change the fact, that GraphQL does not work with Swagger and you have to use other tools.

[freedeveloper]

I have a problem, that maybe someone has a response. I need to expose the graphql point in swagger, because in our enterprise the external address are references through a APIM in Azure. then the script takes the end points to be mapped from the swagger. If the end point is not there (in swagger) is not mapped. are there a simple solution to do this? Thanks in advance

[Antares42]

This answers a different question, namely "how can I build a GraphQL API on top of an existing REST API using its Swagger docs". OP asked how to document a GraphQL API with Swagger.

[Rigin Oommen]

It will be great if there is a unified tool for supporting the documentation of both standards

[tufac2]

There is a playground available. apollographql.com/docs/apollo-server/v2/testing/…

[Christoffer Soop]

While all of the above is true the issue we have is rather: how do we adequately document the GraphQL APIs in a developer portal? It is all good and well to have self-documenting APIs but when you have thirty of forty of them you need to industrialise the documentation around it. And preferably this is done in such a way that it can co-exist with OpenAPI documentation.