Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to document GraphQL with Swagger \ OpenAPI?

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.

like image 331
user12367662 Avatar asked Sep 10 '20 17:09

user12367662


People also ask

Can I use Swagger with 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.

Does OpenAPI support GraphQL?

OpenAPI Specification (OAS), RAML, Blueprint, gRPC, OData, JSON Schema, GraphQL, AsynchAPI and other formats will all be topics at the event, enabling attendees to get familiar with these formats and discuss how to use them in practice.

How do I document a GraphQL API?

Document a GraphQL API 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.

What is OpenAPI-to-GraphQL?

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.

What is Swagger-to-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.

How does OpenAPI work with swagger?

The context around the answer kind of depends on how you interpret OpenAPI/Swagger (I’ll just say OpenAPI going forward). The OpenAPI spec defines routes, and the routes can have QueryString parameters and/or well-defined content that gets included in Request bodies, as well as well-defined content that gets returned in the Response body.


Video Answer


4 Answers

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.

like image 160
Herku Avatar answered Oct 19 '22 22:10

Herku


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.

like image 44
Paul Verest Avatar answered Oct 20 '22 00:10

Paul Verest


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:

GraphQL swagger

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      }    }  }}"
}
like image 23
Thomas Sparber Avatar answered Oct 20 '22 00:10

Thomas Sparber


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.

like image 36
Tomer Bar-Shlomo Avatar answered Oct 19 '22 23:10

Tomer Bar-Shlomo