如何自动创建GraphQL API文档？求推荐仅基于Introspection Schema生成静态文档站点的工具（除GraphQL Voyager外）

Great question! I’ve run into this exact scenario before—when you only have an introspection schema and need clean, static docs for queries and mutations without writing custom examples, there are several reliable tools and workflows to use. Let’s dive in:

CLI Tools #

1. GraphQL Code Generator #

This is a highly flexible tool with plugins specifically built for generating documentation from introspection schemas. It doesn’t require custom use cases—just your schema file.

• Setup: Install the core package and the docs plugin:

  npm install -D @graphql-codegen/cli @graphql-codegen/markdown-docs
  

• Configure: Create a codegen.yml file pointing to your introspection JSON:

  schema: ./path/to/introspection.json
  generates:
    ./docs/graphql-api-docs.md:
      plugins:
        - markdown-docs
  

• Generate: Run the command to build your docs:

  npx graphql-codegen
  

You can then convert the generated Markdown to a static site using tools like MkDocs or Docusaurus for a polished, browsable interface.

2. SpectaQL #

A purpose-built tool for generating beautiful, responsive static GraphQL docs directly from introspection schemas. It automatically organizes queries, mutations, and types with clear formatting.

• Usage: Install and run with your introspection file:

  npx spectaql --schema ./path/to/introspection.json --output ./docs
  

It will generate a complete static HTML site in the ./docs folder, ready to be hosted anywhere—no extra configuration needed for a clean, usable interface.

3. GraphQL Docs Generator #

A lightweight CLI focused on producing concise, structured Markdown docs from introspection schemas. It groups content by queries, mutations, and types, making it easy to scan.

• Usage: Install and generate docs with one command:

  npx graphql-docs-generator ./path/to/introspection.json --output ./docs/api-reference.md
  

Like the other tools, you can pair this with a static site generator to turn the Markdown into a full web-based doc site.

General Workflow for Automated GraphQL Docs #

If you want a repeatable process for generating docs from introspection schemas, follow these steps:

1. Capture the Introspection Schema: If you don’t already have it saved as a JSON file, send an introspection query to your API endpoint (using curl, Postman, or graphql-cli) and save the response. For example:

   npx graphql-cli get-schema -e my-api-endpoint -o introspection.json
   

2. Choose a Tool: Pick one of the CLI tools above based on your preferred output (Markdown vs. ready-to-use HTML).
3. Generate Base Docs: Run the tool to create the initial documentation—all queries, mutations, and type definitions will be pulled directly from the introspection schema.
4. Enhance (Optional): If your schema includes description fields for types/fields, the tools will automatically display them. If not, you can manually add descriptions to the introspection JSON or edit the generated docs to clarify usage.
5. Host (Optional): Deploy the generated static files (HTML or Markdown converted to HTML) to a hosting service like Netlify, GitHub Pages, or your internal server.

内容的提问来源于stack exchange，提问作者Vinay