使用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

相关推荐

  • 多语言-日期格式国际化

    1. 功能概述 多语言切换支持:支持用户填写多种日期、时间格式,并在切换语言后自动匹配对应格式。 自定义格式:用户可以自定义日期时间格式,使其不受语言切换影响。 地址格式:支持不同地区地址格式的自定义。 分位格式设置:支持用户选择数字分组规则,实现千分位或分位的展示效果。 2. 详细配置说明 2.1. 多语言切换 – 创建语言 步骤: 进入“创建语言”页面: 依次选择资源 – 语言 – 语言创建,进入语言创建界面。 填写基本信息: 编码:填写唯一的语言编码,必填。 语言名称:填写语言名称,必填。 语言ISO代码:填写语言的ISO代码,必填。 图标:选择国旗图标,非必填。 书写习惯:选择书写方向(从左向右或从右向左),必填。 一周开始日:选择一周的第一天,必填。 日历:选择日历类型(格里高利历、农历、阳历),必填。 时区:从下拉菜单中选择适合的时区,必填。 日期格式、时间格式:配置用户在不同语言下的6种日期、时间格式,必填。 小数分隔符、整数分隔符:分别设置小数和整数的分隔符,必填。 数字分组规则:默认为3,即千分位设置。 地址格式:设置区域的地址格式,必填。 激活状态:选择激活或无效状态,必填。 当前用户语言:可选择开启或关闭,默认为关。 2.2. 日期与时间格式 步骤: 日期格式:可设置为“年/月/日”、“年月日”等格式。 时间格式:可选择12小时制或24小时制,上午/下午显示等格式。 格式填写规则: 日期格式: 年月日格式需包含年、月、日三个元素。 年月格式仅包含年和月。 时间格式: 时分秒格式包含时、分、秒三个元素。 时分格式仅包含时和分。 注: 在此设置的日期格式应根据个性化爱好自定义日期或时间的显示格式,其中如年月日的格式需要一一对应,不能缺少或增加元素。此处配置的6种格式即对应中文设计器中的6种格式。时间格式同理。 3. 设计器操作指南 3.1. 日期与时间格式自定义 进入设计器: 在设计器中打开属性面板,选择日期或时间相关组件。 选择格式选项: 日期格式:从下拉菜单中选择日期格式,该选项来源于资源-语言-创建语言模块中的填写项。 时间格式:同样从下拉菜单中选择时间格式,选项来源于创建语言模块的填写项。 设置自定义格式: 若选择自定义格式,则在切换语言后该格式将保持不变。 通过手动输入的方式自定义日期或时间格式,无需受限于预设格式。 3.2. 数字分组格式(千分位/分位) 在设计器中配置数字分组: 显示分位:将“显示千分位”修改为“显示分位”,默认为3,即千分位。 配置逻辑: 若局部配置中关闭分位,则数字不进行分组。 若全局配置为2,则局部配置生效的分组规则即为2。 4. 常见问题解答 4.1. Q1. 切换语言后,为什么自定义的日期格式没有变化? 自定义格式在语言切换后保持不变,以确保用户手动选择的格式优先级最高。 Q2. 日期格式填写不符合要求,提示无法保存? 日期格式填写需按照要求,确保格式包含正确的元素(如年月日)。 Q3. 如何确保日期时间显示符合当地习惯? 请在创建语言模块中填写6种日期和时间格式,确保切换语言后格式自动匹配。

    2024年11月12日
    2.1K00
  • 工作流

    1. 查看、处理流程 1.1 流程查看 流程管理页面共同点: 选项分类筛选 标签筛选 应用下拉选筛选 根据流程名称搜索 流程管理页面名词解释: 任务待办:当前登录用户未处理的流程节点 我发起的:当前登录用户人为触发的流程(模型触发) 抄送:抄送给当前登录用户的节点(审批/填写) 我已办结:由当前登录用户完成人工/自动同意、人工拒绝或人工填写的节点 无需办理:当前登录用户转交的任务/被退回、被撤销、被或签、被其他分支任务拒绝的还未办理的任务 1.2 流程处理 1.2.1 任务待办 任务待办中点击“审批/填写”会进入流程详情处理页面,主要展示 1. 操作区 2. 流程发起人及状态 3. 模型视图内容 4. 流程时间线及其他记录。 审批代办操作区可能包含“分享、同意、拒绝、退回、加签、转交、返回”,填写代办操作区可能包含“分享、转交、提交、暂存、返回”,审批/填写操作区包含哪些动作由流程设计决定。 1.2.2 我发起的 我发起的流程列表中主要分为进行中和已完成的流程。进行中的流程可以进行查看、催办、撤销的操作,已完成的流程可以进行查看操作。 查看我发起的流程,进入流程详情页面,也是根据流程状态展示对应操作功能,进行中的流程有分享、催办、撤销、返回按钮,已完成的流程有分享、返回按钮。 1.2.3 抄送 抄送列表中每条抄送只可以进行查看操作,查看进入流程的详情页面,有分享和返回的操作。 1.2.4 我已办结 我已办结列表中可以进行查看操作,查看进入代办的详情页面,可以进行分享和返回的操作。 1.2.5 无需办理 无需办理列表中可以进行查看操作,查看进入代办的详情页面,可以进行分享和返回的操作。 2. 流程运行记录查看 所有运行流程都会记录在流程运行记录中,可以根据流程的所属应用,流程名称,触发方式和状态进行搜索,流程运行记录详情中展示流程运行的具体节点,运行时间,当前运行节点,异常信息等。

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

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

    2024年9月20日
    80300
  • 复制API

    通过API复制功能,用户可以快速基于已有的API创建新的副本,从而减少重复性工作。复制完成后,用户可以根据实际需求修改API副本的详细信息,如名称、描述、请求参数、响应参数等。

    2024年9月20日
    87900
  • 树的展开层级

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

    2024年9月20日
    92100

Leave a Reply

登录后才能评论