使用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 框架或包。

全局安装 GraphiQL
如果你想在本地环境使用 GraphiQL，你可以通过 npm 或 yarn 安装：
如果下载不成功可以使用淘宝镜像源
```
npm install -g graphiql
```
通过 npm 或 Yarn 安装为开发依赖
你也可以将 GraphiQL 作为开发依赖安装到项目中：
```
npm install graphiql
```
生成您的文档！
```
npx spectaql config.yml
```
运行此命令你需要一份config.yml文件。具体使用参考https://github.com/anvilco/spectaql?tab=readme-ov-file#yaml-options

2. 使用JSON格式生成文档

生成或导出 schema 文件

自动生成 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低代码应用平台体验