使用GraphQL生成API文档

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

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

一、使用GraphiQL 工具生成API文档。

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,注意保证工程yml配置文件pamirs.framework.gateway.show-doc: true为开启状态。

    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小时,只要没报错请耐心等待!

二、利用schema.json文件解析生成文档。

如果第一种方式执行失败,可以使用以下方案,利用第一步的GQL请求生成的JSON文件,手动解析json文件生成文档,下面提供一个使用Java代码解析JSON文件的示例,可自行修改生成格式。


示例代码:
gql-schema-api

规则说明:
1、提取内容是"__schema"的types下的内容;
2、"kind": "OBJECT"并且"fields"下"args" 有值时,则接口区域数据,接口名称为name加“/”加"fields"的name 接口描述截取"fields"的description,提取args下的type下的kind为INPUT_OBJECT 提取name值为请求参数名称,fields的type下kind为OBJECT 提取name值为返回参数名称;
3、接口区域数据记录格式,接口地址、接口方式、请求参数名称和返回参数名称以表格展示
4、"kind": "INPUT_OBJECT" 是请求参数区域;提取name值为请求参数名称,提取inputFields 根据name为字段名称,截取description的显示名称 为显示名称,inputFields 的type下的kind为“SCALAR”,提取“name”为字段类型;
5、请求参数区域数据记录格式,请求参数名称、(字段名,字段类型、显示名称、备注)表格展示,备注为空;
6、"kind": "OBJECT" 并且"fields"下"args" 无值时,是返回参数区域;提取fields根据name为字段名称,截取description的显示名称 为显示名称,fields的type下的kind为“SCALAR”,提取“name”为字段类型;
7、返回参数区域记录格式,返回参数名称、(字段名,字段类型、显示名称、备注)表格展示,备注为空;
8、接口名称的name 不需要接口名称为construct、queryByPk、queryListByEntity、queryOneByWrapper
9、接口列表、请求参数数据区域,返回参数数据区域 处理后;
10、在接口列表中的请求参数名称 去查询请求参数数据区域请求参数名称 并把对应的(字段名,字段类型、显示名称、备注)表格展示 展示在对应接口信息后面,
11、在接口列表中的返回参数名称 去查询返回参数数据区域的返回参数名称 并把对应的(字段名,字段类型、显示名称、备注)表格展示 展示在对应接口信息下方的请求参数后面
按照示例json生成python脚本

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日 pm10:18
下一篇 2024年9月18日 pm12:52

相关推荐

  • 表格排序

    表格排序功能允许用户在页面上对表格中的数据进行排序,从而更方便地浏览和分析数据。该功能支持在整个表格层面或单个字段上配置排序规则。通过合理的排序配置,用户可以根据需要查看升序或降序排列的数据。

    2024年10月25日
    48200
  • 管理中心

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

    2024年8月29日
    75100
  • 菜单的配置

    应用中的菜单可以在界面设计器中进入“菜单”页面进行配置。

    2024年9月20日
    50100
  • 元数据在线发布(5.1.0及以上版本)

    一 产品功能说明 1. 设计同步部署 设计同步部署功能实现不同环境设计数据一键同步的目标,即将A环境设计完成的模型、界面、等设计数据一键部署至B环境。 使用此功能,需要在‘应用中心’安装‘应用环境’: ‘应用环境’安装完成,进入发起同步部署环境——>业务应用——>‘应用环境’,对要进行快速部署的发起环境、目标环境进行配置: 在进行多个环境同步部署设计数据时,必须正确配置发起环境、目标环境。 完成配置后,在应用中心,选择目标‘已安装’应用,在操作下拉菜单选择待部署设计类型,即可按照指引完成操作: 2. 设计导出 设计导出功能具备将已安装应用所属(应用技术名称)设计元数据,如模型、界面、流程、集成设计、数据可视化导出为json文件的能力,具备筛选导出、一键导出两种方式以满足不同业务场景需要。 目标是实现在多个环境通过技术接口调用、或通过应用中心导入界面完成导入,使设计元数据在不同环境之间快速迁移同步: 因平台允许多个应用名称相同,能够唯一定位具体应用使用的是‘应用技术名称’,因此识别应用标识的依据为应用技术名称。 3. 设计导入 3.1. 迁移导入 对于已导出设计元数据json文件,如果导出类型为‘迁移导出’,可以在不同环境,通过应用中心——>已安装应用——>设计导入(迁移),实现设计数据导入: 3.2. 标品导入 对于导出类型为‘标品导出’的设计元数据,目前只支持通过技术接口形式完成导入,暂不支持界面进行可视化导入操作。 4. 导出导入任务 不同环境设计元数据以导入json文件方式进行迁移的基础是设计导出,基于界面导入实现设计元数据在不同环境进行迁移场景、或通过技术接口导入以实现标品升级的场景,存在导出类型为迁移导出、标品导出的区别。 使用此功能的操作者需要依据实际需求场景进行相应导出类型的选择。 4.1. 导出任务查看 对于已经执行导出的任务,可通过‘应用环境——>设计导出’查看导出任务信息: 4.2. 导入任务查看 对于已经执行导入的任务,可通过‘应用环境——>设计导入’查看导入任务状态、进度、详细信息: 5. 部署任务 部署任务功能用于查看设计数据同步部署功能任务状态、详细信息;分为发起环境任务查看、目标环境任务查看。 无论是发起环境,或是目标环境,均通过所属环境‘应用环境’中‘部署任务’功能进行查看: 二 产品功能操作手册 1. 设计导出 1.1. 环境迁移导出 点击‘业务应用——>应用中心’,进入应用中心,默认显示‘应用列表’标签页: 选择‘已安装’应用——>操作,出现操作菜单: 选择‘设计导出’,显示支持导出的各设计项: 1.1.1. 模型导出 操作菜单选择‘模型导出’: 打开模型导出信息弹窗: 在弹窗页中存在要素信息项及操作项: 导出类型:选择‘迁移导出’。 文件名称:默认为‘应用名称+设计类型’。 导出模式:异步模式,不可修改。 导出格式:JSON文件,不可修改。 一键导出:操作项,直接导出当前应用下的所有无代码模型,不需要筛选。 筛选导出:操作项,进入无代码模型导出筛选页,选择要导出的设计数据。 1.1.1.1. 一键导出 点击‘一键导出’,关闭弹窗,回到应用中心,右上角出现导出进行中提示信息: 导出任务状态信息、导出任务详细信息查看方式参见《1.3 设计导出/导出任务查看》。 1.1.1.2. 筛选导出 点击‘筛选导出’,进入无代码模型导出筛选页: 筛选页面按照‘模型类型’、‘可用/废弃’、‘来源’选择或输入查找条件,点击‘搜索’,进行条件搜索,查找满足条件无代码模型: 点击‘重置’按钮,清空已输入查找条件: 点击列表标题栏勾选框,可进行全选/取消全选操作,全选——选择全部模型,取消全选——取消所有已勾选项: 勾选要导出模型,点击‘导出’按钮: 回到应用中心,右上角提示导出信息: 导出任务状态信息、导出任务详细信息查看方式参见《1.3 设计导出/导出任务查看》。 1.1.2. 界面导出 ‘业务应用——>应用中心’,进入应用中心,选择已安装应用——>操作——>设计导出——>界面导出,弹出界面导出信息项弹窗,‘导出类型’选择‘迁移导出’: 1.1.2.1. 一键导出 点击‘一键导出’,关闭弹窗,回到应用中心,右上角出现导出进行中提示信息: 界面导出会将所选菜单项、菜单目录路径、菜单绑定页面、页面使用的自定义组件全部导出为json文件。 导出任务状态信息、导出任务详细信息查看方式参见《1.3 设计导出/导出任务查看》。 1.1.2.2. 筛选导出 点击‘筛选导出’,进入应用环境——>界面导出筛选页面,显示当前应用下所有菜单项: 查询项‘菜单名称’输入名称,点击‘搜索’按钮,进行模糊查找匹配的菜单项: 点击‘清除’按钮,清除已输入的查询内容: 勾选菜单项后,点击‘导出’按钮: 回到应用中心页面,同时页面右上角提示导出进行中信息: 界面导出会将所选菜单项、上级菜单目录项、菜单绑定页面、页面使用的自定义组件全部导出为json文件。 导出任务状态信息、导出任务详细信息查看方式参见《1.3 设计导出/导出任务查看》。 1.1.3. 流程导出 点击‘业务应用——>应用中心’,进入应用中心,选择已安装应用——>操作——>设计导出——>流程导出,弹出导出信息弹窗: ‘导出类型’选择‘迁移导出’。 1.1.3.1. 一键导出 点击‘一键导出’: 关闭弹窗,回到应用中心,右上角出现导出进行中提示信息: 一键导出流程数据会按照应用技术名称,将当前应用下所有流程、元数据、涉及的业务数据如审批用户、角色等全部导出为json文件。 导出任务状态信息、导出任务详细信息查看方式参见《1.3 设计导出/导出任务查看》。 1.1.3.2. 筛选导出 点击‘筛选导出’: 进入流程数据筛选页面,显示当前应用(技术名称)下所有已发布流程: 支持按照流程名称(模糊匹配)、触发方式(模型触发、定时触发、日期触发、子流程)进行筛选;输入筛选条件,点击搜索按钮,查找匹配结果: 点击‘清除’按钮,清空筛选内容: 勾选列表流程项,点击‘导出’按钮: 返回应用中心,同时页面右上角提示导出信息: 流程导出会将应用(技术名称)下的所有已发布流程及相关元数据、业务数据全部导出为json文件。 导出任务状态信息、导出任务详细信息查看方式参见《1.3 设计导出/导出任务查看》。 1.1.4. 集成导出 点击‘业务应用——>应用中心’,进入应用中心,选择已安装应用——>操作——>设计导出——>集成导出,弹出集成导出信息项弹窗,‘导出类型’选择‘迁移导出’: 1.1.4.1. 一键导出 点击‘一键导出’,关闭弹窗,回到应用中心,右上角出现导出进行中提示信息: 一键导出集成数据会按照应用技术名称,将所有已发布数据流程;以及所有已启用连接器(与应用无关)、已启用开放接口(与应用无关)全部导出为json文件。 导出任务状态信息、导出任务详细信息查看方式参见《1.3 设计导出/导出任务查看》。 1.1.4.2. 筛选导出 点击‘筛选导出’: 进入集成数据筛选页面,默认显示‘连接器’标签页——>应用(已启用)数据项列表: 可选项: 连接器:应用(已启用状态)、数据库(已启用状态)、与应用无关。 数据流程:已发布状态,且属于发起导出应用(技术名称)下的数据流程。 开放平台:API接口(已启用状态)、与应用无关。 以上各项在列表中展示的数据均可勾选并支持导出为json文件: 勾选列表数据项,点击‘导出’按钮: 回到应用中心,右上角显示导出提示信息: 导出任务状态信息、导出任务详细信息查看方式参见《1.3 设计导出/导出任务查看》。 1.1.5. 数据可视化导出 点击‘业务应用——>应用中心’,进入应用中心,选择已安装应用——>操作——>设计导出——>数据可视化导出,弹出数据可视化导出信息项弹窗,‘导出类型’选择‘迁移导出’: 1.1.5.1. 一键导出 点击‘一键导出’: 关闭弹窗,回到应用中心,右上角出现导出进行中提示信息: 一键导出数据可视化会将所有已发布图表(含路径目录)、报表(含路径目录)、数据大屏(含路径目录)、图表模版全部导出为json文件。 导出任务状态信息、导出任务详细信息查看方式参见《1.3 设计导出/导出任务查看》。 1.1.5.2. 筛选导出 点击‘筛选导出’: 进入数据可视化筛选列表页面,默认显示‘图表’标签页,并展示已发布图表数据项列表: 标签页: 图表:显示所有已发布状态图表,以树形结构展示,支持按照‘图表名称’模糊匹配查找。 报表:显示所有已发布状态报表,以树形结构展示,支持按照‘报表名称’模糊匹配查找。 数据大屏:显示所有已发布状态数据大屏,以树形结构展示,支持按照‘数据大屏名称’模糊匹配查找。 图表模版:显示所有图表模版,列表形式展示,支持按照‘图表名称’模糊匹配查找。 勾选列表数据项,点击‘导出’按钮: 关闭弹窗,回到应用中心,右上角出现导出进行中提示信息: 筛选导出数据可视化数据会将所有已发布图表(含路径目录)、报表(含路径目录)、数据大屏(含路径目录)、图表模版全部导出为json文件。 导出任务状态信息、导出任务详细信息查看方式参见《1.3 设计导出/导出任务查看》。 1.2. 标品导出 点击‘业务应用——>应用中心’,进入应用中心,点击‘应用列表’标签项;选择‘已安装’应用,点击操作,出现操作菜单: 选择‘设计导出’,显示支持导出的各设计项: 1.2.1. 模型导出 点击‘业务应用——>应用中心’,进入应用中心;点击已安装应用——>操作,出现操作菜单: 选择‘设计导出——>模型导出’: 打开导出信息弹窗: 1.2.1.1. 一键导出 导出过程同《1.1.1.1 设计导出/环境迁移导出/模型导出/一键导出》,区别是标品导出json文件无法通过前端页面导入其它环境,只能通过技术接口导入。 导出任务状态信息、导出任务详细信息查看方式参见《1.3 设计导出/导出任务查看》。 1.2.1.2. 筛选导出 导出过程同《1.1.1.2 设计导出/环境迁移导出/模型导出/筛选导出》,区别是标品导出json文件无法通过前端页面导入其它环境,只能通过技术接口导入。 导出任务状态信息、导出任务详细信息查看方式参见《1.3 设计导出/导出任务查看》。 1.2.2.…

    2024年9月2日
    48900
  • 权限手册(5.1以上)

    此手册基于5.0版本的权限系统,新增了角色管理中的权限配置功能。对于5.0版本的权限功能说明,请参考此前发布的权限手册:https://doc.oinone.top/auth/14357.html。本手册仅介绍新增的功能,其他功能详见此前的版本手册。

    2024年9月26日
    1.6K00

Leave a Reply

登录后才能评论