How to document GraphQL with Swagger \ OpenAPI?

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.

Leave a Comment