Dokumentieren Sie eine GraphQL-API

Question

Mit REST können wir Swagger, RAML oder andere Technologien verwenden, um unsere API zu dokumentieren und eine HTML-Dokumentation zu generieren, die unsere Kunden lesen können, ohne dass eine Interaktion mit den Servern erforderlich ist.

Gibt es etwas Ähnliches für GraphQL? Gibt es eine Möglichkeit, eine Dokumentation von Ressourcen und Eigenschaften zu generieren?

Answer 1

Es sieht aus wie es ist jetzt https://www.npmjs.com/package/graphql-docs

Dynamisch generierter Dokumentationsexplorer für GraphQL Schemas. Es zielt darauf ab, einen besseren Überblick über ein Schema als GraphiQL zu geben, jedoch ohne Features abzufragen.

Sie können auch eine statische Dokumentation auf einer Schemadatei oder GraphQL Endpunkt basierend erzeugen:

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

Answer 2

Nach meinem Wissen gibt es noch kein Tool, das automatisch HTML-Dokumentation für eine GraphQL-API generiert, aber ich fand GraphiQL sogar noch nützlicher als jede API-Dokumentation in HTML, die ich gesehen habe.

GraphiQL können Sie interaktiv das Schema eines GraphQL-Servers untersuchen und Abfragen gleichzeitig ausführen. Es verfügt über Syntax-Hervorhebung, Autovervollständigung und es sagt Ihnen sogar, wenn Ihre Abfrage ungültig ist, ohne sie auszuführen.

Wenn Sie nach statischen Dokumentationen suchen, habe ich es ziemlich praktisch gefunden, das Schema in der GraphQL-Schemasprache zu lesen. Dank einer weiteren großartigen Funktion von GraphQL - Schema Introspection - können Sie das Schema für jeden Server, auf den Sie Zugriff haben, einfach ausdrucken. Führen Sie einfach die introspection query gegen den Server und dann wie so das resultierende Selbstbeobachtung Schema drucken (graphql-js verwenden):

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

Das Ergebnis wird wie folgt aussehen:

# 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 
} 

Answer 3

I Statische Seite Generator für die Dokumentation GraphQL Schema gefunden. GitHub link.

HTML-Export sieht so aus.

GitHub GraphQL doc example