Dokumentacja interfejsu API GraphQL API

Question

Dzięki REST możemy korzystać z Swagger, RAML lub innych technologii do dokumentowania naszego API i generowania dokumentacji HTML, którą nasi konsumenci mogą przeczytać bez potrzeby interakcji z serwerami.

Czy istnieje coś podobnego do GraphQL? Czy istnieje sposób na wygenerowanie dokumentacji zasobów i właściwości?

Answer 1

Wygląda na to, że jest teraz https://www.npmjs.com/package/graphql-docs

Dynamicznie generowany eksplorator dokumentacji dla schematów GraphQL. Ma on na celu zapewnienie lepszego przeglądu schematu niż GraphiQL, ale bez funkcji zapytań.

Można również wygenerować statyczny plik dokumentacji w oparciu o pliku schematu lub GraphQL końcowego:

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

Answer 2

Według mojej wiedzy nie ma jeszcze narzędzia, które automatycznie generuje dokumentację HTML dla API GraphQL, ale znalazłem GraphiQL, aby było jeszcze bardziej przydatne niż jakakolwiek dokumentacja API w HTML, którą widziałem.

GraphiQL pozwala interaktywnie przeglądać schemat serwera GraphQL i uruchamiać kwerendy przeciwko niemu w tym samym czasie. Ma podświetlanie składni, autouzupełnianie, a nawet informuje cię, kiedy zapytanie jest nieprawidłowe, bez jego wykonywania.

Jeśli szukasz statycznej dokumentacji, odkryłem, że dość wygodne jest odczytywanie schematu w języku schematów GraphQL. Dzięki kolejnej wspaniałej funkcji GraphQL - schema introspection - możesz łatwo wydrukować schemat dla dowolnego serwera, do którego masz dostęp. Wystarczy uruchomić introspection query przeciwko serwera, a następnie wydrukować wynikowy schematu introspekcję jak tak (za pomocą graphql-js):

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

wynik będzie wyglądać następująco:

# 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

znalazłem generator statyczne strony do dokumentowania GraphQL schematu. GitHub link.

Eksport HTML wygląda następująco.

GitHub GraphQL doc example