使用GraphQL生成API文档

GraphiQL 是一个非常流行的交互式开发环境(IDE),专门用于浏览、编写和测试 GraphQL 查询。它不仅可以帮助你查询 API,还可以自动生成文档。以下是如何使用 GraphiQL 的具体步骤:

仓库地址:https://github.com/anvilco/spectaql?tab=readme-ov-file#yaml-options

1. GraphiQL 安装与配置

方式 : 本地或全局安装 GraphiQL

如果你的 GraphQL API 服务器没有内置 GraphiQL,你可以使用独立的 GraphiQL 框架或包。

  1. 全局安装 GraphiQL
    如果你想在本地环境使用 GraphiQL,你可以通过 npmyarn 安装:
    如果下载不成功可以使用淘宝镜像源

    npm install -g graphiql
  2. 通过 npm 或 Yarn 安装为开发依赖
    你也可以将 GraphiQL 作为开发依赖安装到项目中:

    npm install graphiql
  3. 生成您的文档!

    npx spectaql config.yml

    运行此命令你需要一份config.yml文件。具体使用参考https://github.com/anvilco/spectaql?tab=readme-ov-file#yaml-options

2. 使用JSON格式生成文档

生成或导出 schema 文件

  1. 自动生成 schema
    如果你使用的是 Java 类和注解方式定义的 GraphQL API(使用 @GraphQLQuery 等注解),GraphQL schema 通常在运行时生成。你可以使用 Spring Boot 启动后访问 GraphQL endpoint 来手动导出 schema。

    • 访问 GraphQL Endpoint:在应用运行时,GraphQL API 通常暴露在 /graphql 路径下。你可以通过 introspection 查询导出完整的 GraphQL schema。

    下面是一个 introspection 查询的示例,它可以帮助你获取 schema:这个查询可根据文档需要动态调整。查询http://127.0.0.1:8091/pamirs/graphql

    query IntrospectionQuery {
     __schema {
       queryType { ...FullType }
       mutationType { ...FullType }
       subscriptionType { name }
       types {
         ...FullType
       }
       directives {
         name
         description
         locations
         args {
           ...InputValue
         }
       }
     }
    }
    
    fragment FullType on __Type {
     kind
     name
     description
     fields(includeDeprecated: true) {
       name
       description
       args {
         ...InputValue
       }
       type {
         ...TypeRef
       }
       isDeprecated
       deprecationReason
     }
     inputFields {
       ...InputValue
     }
     interfaces {
       ...TypeRef
     }
     enumValues(includeDeprecated: true) {
       name
       description
       isDeprecated
       deprecationReason
     }
     possibleTypes {
       ...TypeRef
     }
    }
    
    fragment InputValue on __InputValue {
     name
     description
     type { ...TypeRef }
     defaultValue
    }
    
    fragment TypeRef on __Type {
     kind
     name
     ofType {
       kind
       name
       ofType {
         kind
         name
         ofType {
           kind
           name
           ofType {
             kind
             name
             ofType {
               kind
               name
             }
           }
         }
       }
     }
    }

    你可以将这个查询放在 GraphiQL(开发工具)或者 Postman 等工具中,发送请求到 /graphql,这样可以获得完整的 schema。

将请求的响应保存为JSON文件,在config.yml中配置。配置参考:https://github.com/anvilco/spectaql/blob/main/config-example.yml

spectaql:
  # Optional path to the target build directory.
  # Set to null to not write the output to the filesystem, making it only available via the API (default: public)
  #
  # Default: public
  targetDir: /Users/mmy/Desktop
  themeDir: /Users/mmy/Desktop

introspection:
  # File containing a GraphQL Schema Definition written in SDL.
  # Can also pass an array of paths (or glob supported by @graphql-tools/load-files)
  # like so:
  # schemaFile:
  #   - path/to/schema/part1.gql
  #   - path/to/schema/part2.gql
#  schemaFile: /Users/mmy/Desktop/schema2.graphql

  # File containing Introspection Query response in JS module export, or JSON format
  introspectionFile: /Users/mmy/Documents/response2.json
#
  # URL of the GraphQL endpoint to hit if you want to generate the documentation based on live Introspection Query results
  # NOTE: If not using introspection.url OR servers[], you need to provide x-url below
#  url: 'http://127.0.0.1:8091/pamirs/graphql'

extensions:
  # Utilize the 'graphql-scalars' library when generating examples for scalars it supports that
  # do not have an example already set via some other method. Usually this is a good
  # thing to have on, but it is possible to turn it off.
  # Default: true
  graphqlScalarExamples: true

servers:
  - url: http://127.0.0.1:8091/pamirs/base

运行命令npx spectaql config.yml就可以得到一份html的API文档啦!

作者注:这行命令生成文档的执行时间和文件大小息息相关。平台接口执行时间大概1-2小时,只要没报错请耐心等待!

Oinone社区 作者:yexiu原创文章,如若转载,请注明出处:https://doc.oinone.top/chan-pin-shi-yong-shou-ce/17412.html

访问Oinone官网:https://www.oinone.top获取数式Oinone低代码应用平台体验

(0)
yexiu的头像yexiu数式员工
上一篇 2024年9月12日 下午10:18
下一篇 2024年9月18日 下午12:52

相关推荐

  • 工作流

    抱歉,您没有查看此内容的权限,您可以登录后填写下方表单申请权限

    您暂未登录或注册,请登录或注册后提交

    2024年6月20日
    59900
  • 跳转动作新增默认生成视图

    在跳转动作的配置中,针对用户在选择创建新页面时需要重新拖动字段到设计器区的操作,新增了“默认生成视图”功能。这一功能可以自动生成页面视图,简化了设计流程,提升了操作效率。

    2024年9月20日
    57600
  • 多语言-日期格式国际化

    1. 功能概述 多语言切换支持:支持用户填写多种日期、时间格式,并在切换语言后自动匹配对应格式。 自定义格式:用户可以自定义日期时间格式,使其不受语言切换影响。 地址格式:支持不同地区地址格式的自定义。 分位格式设置:支持用户选择数字分组规则,实现千分位或分位的展示效果。 2. 详细配置说明 2.1. 多语言切换 – 创建语言 步骤: 进入“创建语言”页面:…

    2024年11月12日
    62400
  • 管理中心

    管理中心由原「合作伙伴中心」「用户中心」「权限」3部分构成。

    2024年8月29日
    63100
  • 树的展开层级

    默认配置展开到哪一层级。

    2024年9月20日
    64500

发表回复

登录后才能评论