记录GraphQL API

4 回答

• 3

  看起来好像现在https://www.npmjs.com/package/graphql-docs

  动态生成的GraphQL架构文档资源管理器 . 它旨在提供比GraphiQL更好的模式概述，但不需要查询功能 .

  

  您还可以基于模式文件或GraphQL endpoints 生成静态文档文件：

  npm install -g graphql-docs
  graphql-docs-gen http://GRAPHQL_ENDPOINT documentation.html
  

  回复于 2024-04-28T13:55:57+08:00
• 20

  据我所知，还没有为GraphQL API自动生成HTML文档的工具，但我发现GraphiQL比我见过的HTML中的任何API文档都更有用 .

  GraphiQL允许您以交互方式浏览GraphQL服务器的模式，并同时对其运行查询 . 它具有语法高亮，自动完成功能，甚至可以在不执行查询的情况下告诉您查询何时无效 .

  如果您发现使用GraphQL架构语言读取架构非常方便 . 由于GraphQL的另一个重要功能 - 模式内省 - 您可以轻松地为您有权访问的任何服务器打印模式 . 只需对服务器运行introspection query然后打印生成的内省模式（使用graphql-js）：

  var graphql = require('graphql');
  var introspectionSchema = {}; // paste schema here
  console.log(graphql.printSchema(graphql.buildClientSchema(introspectionSchema)));
  

  结果将如下所示：

  # An author
  type Author {
    id: ID!
  
    # First and last name of the author
    name: String
  }
  
  # The schema's root query type
  type Query {
  
    # Find an author by name (must match exactly)
    author(name: String!): Author
  }
  

  回复于 2024-04-28T13:55:57+08:00
• 7

  我找到了用于记录GraphQL Schema的静态页面生成器 . GitHub link .

  HTML导出看起来像这样 .

  

  GitHub GraphQL doc example

  回复于 2024-04-28T13:55:57+08:00
• 11

  实际上，Graphql在Facebook的内置 Graphiql 或第三方工具（如 Altair ）中非常自我记录，因为列出了查询/突变，并且还显示了返回类型 .

  我发现需要doc的一个地方是输入查询参数，可能需要 specific format . 这可以通过添加评论 on top of 那些 arguments 来实现 .

  type Query {
        eventSearch(
          # comma separated location IDs. (eg: '5,12,27')
          locationIds: String,
          # Date Time should be ISO 8601: 'YYYY-DD-MM HH:mm:ss'. (eg: '2018-04-23 00:00:00')
          startDateTime: String!,
          endDateTime: String!): [Event]
    }
  

  它将如下所示：

  Graphiql：

  

  Altair：

  

  回复于 2024-04-28T13:55:57+08:00