Creating Static Documentation For GraphQL APIs Using GraphQL SDL

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 any API Templates already available or designing a custom GraphQL schema. For this post, you'll be using the API Template for the OpenWeatherMap API that can provide us with weather reports for over 200,000 cities worldwide, based on addresses or coordinates.

To set up a new GraphQL API with StepZen, you need to create an account first and follow the getting started steps here. After which, you need to create a new directory and move into that directory on your local machine first:

mkdir my-api && cd my-api

In this directory, you can run the following command that will import the API Template for the OpenWeatherMap API:

stepzen import openweathermap

The CLI will then ask you to provide a name for the endpoint, the suggested name, or a custom one. For this post, you can name the endpoint: api/weatherreport.

You don't need an API key to use the OpenWeatherMap API, so you can get started with exploring the API right away. After the import of the API Template has been completed, you can run the command:

stepzen start

Which will create a GraphQL API based on the GraphQL SDL defined in index.graphql and weatherreport/weatherreport.graphql in your local directory. This GraphQL API will be available through a local proxy at weatherreport/weatherreport.graphql or directly from https://{stepzen_username}.stepzen.net/api/weatherreport/__graphql (replace {stepzen_username} with your own).

Through GraphiQL, you can see one operation defined in the GraphQL schema, the weatherReport query. This query 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.

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 GraphQL with StepZen, using the following query:

query GetWeatherReport {
  weatherReport(latitude: 38.897663, longitude: -77.036574) {
    description
    feelsLike
    latitude
    longitude
    temp
    units
    date
  }
}

The response of this API will be returned on the second panel in our GraphiQL interface, as you can see in the image below.

You can find more information on the response by using the schema tab in GraphiQL 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 GraphiQL playground can be very helpful.

Creating static documentation

The official 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 can configure SpectaQL using a config.yaml file that you can place in the root of your project:

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 GraphiQL playground](http://localhost:5000/api/weatherreport)'
  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.

This GraphQL API will be available through a local proxy at weatherreport/weatherreport.graphql or directly from https://{stepzen_username}.stepzen.net/api/weatherreport/__graphql (replace {stepzen_username} with your own).

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.

When you're running stepzen start on your local machine, it will also make an instance of GraphiQL available at http://localhost:5000/api/weatherreport; this endpoint is only available on your local device. It shouldn't be used to access this GraphQL API unless to use GraphiQL.

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:

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. There is no additional information available for the operations of return types yet, but you can directly add these in the GraphQL SDL. These descriptions in the schema will be parsed by SpectaQL and displayed in the static documentation. In the file weatherreport/weatherreport.graphql, you can add the following:

"""
A type that describes the weather report and its
fields
"""
type WeatherReport {
  date: Date!
  "City geo location, latitude"
  latitude: Float!
  "City geo location, longitude"
  longitude: Float!
  temp: Float
  feelsLike: Float
  description: String
  units: String
}

type Query {
  """
  Call current weather data for one location by
  geographic coordinates
  """
  weatherReport(
    "City geo location, latitude"
    latitude: Float!
    "City geo location, longitude"
    longitude: Float!
  ): WeatherReport
    @connector(
      type: "__openweathermap_weather_location_connector__"
      configuration: "owm_default"
    )
}

Descriptions for the type WeatherReport and the weatherReport query 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 GraphiQL playground and the static documentation generator from SpectaQL.

Or view the description directly from GraphiQL, which you can reach at the URL http://localhost:5000/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 codes, 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 the repository with the complete source code for this post here.

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