如何使用 Swagger OpenAPI 记录 GraphQL? [英] How to document GraphQL with Swagger OpenAPI?

问题描述

如何使用 Swagger 记录 GraphQL?我们有一个巨大的后端 REST API，它最近已经部分开始使用 GraphQL.为了记录 API，我们使用 Swagger.

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.

问题是:如何使用 Swagger(OpenAPI) 来记录 GraphQL 端点?Swagger 或 GraphQL 的官方文档中绝对没有相关信息.

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.

推荐答案

GraphQL API 通常通过 GraphQL 服务器本身提供的文档工具来记录:类型系统以及类型和字段的描述.GraphQL playground 之类的工具可让您通过在可视化文档中单击/搜索来探索 API 文档树或通过 IDE 之类的功能(自动完成 + 工具提示).这主要是公司公开其公共 GraphQL API 的方式.一些公司还公开 swagger 之类的文档(例如 Github v4 API 文档).此工具可以为您的 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. 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 为 REST API 解决了这个问题.因此，Swagger 是为不同的生态系统构建的.Swagger 向 REST 添加了在 GraphQL 中开箱即用的功能.因此，据我所知，任何一方都没有尝试创建兼容性.有一些工具可以将 Swagger/OpenAPI REST 端点公开为 GraphQL 查询，这在您的过渡期可能会很有趣.

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.

这篇关于如何使用 Swagger OpenAPI 记录 GraphQL?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！