The main reason for writing API documentation is to make your API understandable to other developers that want to use it. GraphQL APIs often only have an interactive playground available that serves as a sandbox for the API and documentation. But working with GraphQL can be very confusing to developers that only worked with REST APIs in the past, making a playground-like GraphiQL hard to use. It makes perfect sense for developers new to GraphQL and non-technical people to add static documentation with references to interactive examples to your API. In the same way, as you can dynamically create documentation for REST APIs based on OpenAPI or Swagger specification, you can also generate documentation based on GraphQL SDL. In this post, you'll be learning how to do this using StepZen API templates and a library called SpectaQL.

TL;DR: You can find the repository with the complete source code for this post here.

Setting up a GraphQL API with StepZen

Before you can create documentation, you need to create a GraphQL API first. With StepZen, you can create GraphQL APIs within minutes by using using your existing data source like a database or REST API. For this post, you'll be using the OpenWeatherMap API that's available in StepZen GraphQL Studio. This API can provide us with weather reports for over 200,000 cities worldwide, based on addresses or coordinates.

To use the OpenWeatherMap API, you need to request a free API Key or used mocked data from StepZen GraphQL Studio.

In StepZen GraphQL Studio, you can try out the GraphQL-version of the OpenWeatherMap API - either with real data or mocked data in case you don't have requested an API Key. The sample query that you see in StepZen GraphQL Studio requires you to provide coordinates, which are values for latitude and longitude. To get these values, you can use geocoding to transform any address into a combination of latitude and longitude, making it easy to highlight it on a map. There are several ways to get these values from the browser using a Geolocation API or to use third-party APIs. The first one is the easiest when you're building a web application, so let's use the second option for now. One of the most popular third-party APIs for geocoding is the Google Maps API. With this API, you can request geocoding information based on an address, the White House in Washington D.C., and get the latitude longitude combination.

You can use the APIs from Google Maps if you have requested an API Key, but you can also use it through the Maps JavaScript API, accessible from their documentation directly.

Google Maps API Geocoding

With the address 1600 Pennsylvania Avenue, Washington, D.C., USA, you receive the coordinates 38.897663 and -77.036574, the latitude-longitude combination.

With these coordinates, you can check today's weather at the White House using the OpenWeatherAPI that we've made available through StepZen GraphQL Studio, using the following query:

query OpenWeatherQueries(
  $openweather_appid: Secret!
) {
  openweather_weatherForecast(
    openweather_appid: $openweather_appid
    lat: 38.897663
    lon: -77.036574
    units: imperial
  ) {
    current {
      humidity
      clouds
      feels_like
      weather {
        description
      }
    }
  }
}

The response of this API will be returned on the third panel in the GraphQL Studio interface, as you can see in the image below.

StepZen GraphQL Studio with for OpenWeatherMap API

You can find more information on the response by using the "Documentation" tab in GraphQL Studio on the right, which tells us the meaning of the variables. You now know that the response includes a description of the weather (like cloudy with a chance of sun), the temperature, and the temperature unit.

But if you're not familiar with GraphQL or haven't created a query yourself before, this way of introspecting a GraphQL API can be very confusing. Therefore, having static documentation next to interactive documentation in a GraphQL playground can be very helpful.

Creating static documentation

The offical documentation of OpenWeatherMap REST API is an excellent example of static documentation. It provides both text and code examples to get you started on using the API. For REST APIs the documentation is often generated from their API specification, defined in an Open API or Swagger format. GraphQL APIs don't have a specification in this format but instead rely on their schema. In the previous section, you used the GraphiQL playground, which uses an introspection query to get all the information from our GraphQL API using its schema. This introspection query can, however, also generate static documentation for this GraphQL schema.

For this, we'll be using a library called SpectaQL, which is based on the popular library Spectacle that works with Open API and Swagger specifications. SpectaQL can be installed globally on your machine from npm:

npm install -g spectaql

After the installation is complete, you should create a new project directory:

mkdir openweather-spectaql && cd openweather-spectaql

And can configure SpectaQL using a config.yaml file that you can place in this directory:

spectaql:
  logoFile: ./logo.svg

introspection:
  url: '{{stepzen_api_endpoint}}'
  headers:
    Authorization: 'apikey {{stepzen_api_key}}'

info:
  title: StepZen - OpenWeatherMap GraphQL API
  description:
    'Access current weather data for any location on Earth including over 200,000 cities. Using GraphQL!


    [View GraphQL playground](https://graphql.stepzen.com/openweather)'
  contact:
    name: StepZen Support
    url: https://stepzen.com/docs
    email: support@stepzen.com

servers:
  - url: '{{stepzen_api_endpoint}}'
    description: Production
    production: true

In this file, we've configured that the GraphQL API is available at {{stepzen_api_endpoint}}, which you should replace with the endpoint to where the GraphQL instance of the OpenWeatherMap API is running. When using StepZen GraphQL Studio, you can find the GraphQL endpoint in the top-right of you screen when you press "Publish".

You'll also need to define your StepZen API Key ({{stepzen_api_key}}), which you can find on your account page, as this URL is only accessible with authentication for security reasons. Also, we've passed additional metadata like a logo, description, and contact details that will be added to the documentation.

You should now be able to run SpectaQL to create the documentation, which could take up to 1 minute depending on your machine, with the following command:

npx spectaql -D config.yml

SpectaQL will create your documentation in a new directory called public consisting of JavaScript, HTML, and CSS. The local path to a logo file that you defined in config.yml will is used to copy the logo to this newly created directory. You can view the documentation by opening the file public/index.html in a browser, which should look something like the following:

Static documentation with SpectaQL

Besides the metadata you configured in config.yml, this APIs GraphQL schema lists all the possible operations and types and is introspected to document them.

Descriptions for types and queries in the OpenWeatherMap schema are added as multi-line descriptions, while the fields and arguments for these types are added in a single line. When these descriptions are included in the schema, they will also be available through an introspection query. This is important, as the introspection query adds the schema information to both the GraphQL playground and the static documentation generator from SpectaQL.

Detailed descriptions using GraphQL SDL

Or view the description directly from GraphiQL, which you can reach at the URL http://localhost:5001/api/weatherreport.

Conclusion and next steps

Documentation for any GraphQL API starts with an introspection query, a simple but powerful way to explore any GraphQL API. The introspection query will give you information on the GraphQL schema and is used by other tools like GraphiQL and SpectaQL. With GraphiQL, you get access to a playground that lets you introspect the GraphQL schema and execute the available operations for a GraphQL endpoint. But having a playground like GraphiQL isn't sufficient if you want users of all levels to integrate with your GraphQL API. Therefore adding static documentation about your endpoint can be a good addition. With the open-source library SpectaQL, you can do all this with just a few lines of code, making it almost as simple as building and deploying a GraphQL API with StepZen. Also, you can add descriptions for type, fields, arguments, and operations using just GraphQL SDL.

What comes next? So far, you've learned how to create static documentation based on a GraphQL API locally, but the next step would be to integrate this into your CI/CD and deploy this documentation on a server. Combining with your CI/CD can be done by adding the command to run SpectaQL to your deployment steps. At the same time, StepZen can be integrated with Netlify to deploy the static documentation. You can find a repository with more example code from SpectaQL here.

Want to learn more about StepZen? Try it out here or ask any question on the Discord here.