Skip to content

Latest commit

 

History

History
74 lines (50 loc) · 3.91 KB

generate-api-documentation.md

File metadata and controls

74 lines (50 loc) · 3.91 KB
Raw

Generating API documentation

Overview

This document discusses how to create a static documentation page for our API.

As of right now, there is no static page with our API documentation, so if any problem occurs the user can either check the examples directory or read the schema on his own.

Requirements

  • Static page hosted on Compass
  • Shows how the requests should look like
  • Utilises our example requests
  • The examples are compatible with the Director version

Possible solutions

1. Links to the examples on the API playground

The GraphQL playground that we use on our endpoints generates documentation with comments from the schema. We could create a gqlgen plugin that would add a relative example link to every query and mutation. The example files would be stored inside the Director images and available on a GET request to /director/examples/{file-name}.graphql. That way the user would be able to check how the request looks right away.

POC can be found here

Work that has to be done

  • create the gqlgen plugin
  • host and serve the examples on the director
  • make sure that GET requests on the director require no authentication
  • create an html template to which to insert the example

Pros

  • relatively small amount of work to be done
  • examples are compatible with the Director version
  • requires almost no maintenance

Cons

  • requires some amount of work to serve pretty GraphQL examples

2. Using a 3rd party tool to generate static html

Dociql is a tool that generates html files with the documented schema. It uses the introspection query to fetch the API schema and a YAML file to configure the output. An example config can be found here With the config file we can define the use cases of our schema and group it by domains. It also creates a sample request and response with a 'Try it now button'. The files would be stored inside the director image and hosted on one of its endpoints

Unfortunately it does not meet every requirement. In order for dociql to work we would have to fork it/contribute to it and made the following changes:

  • Handle authentication

Dociql does not support authentication out of the box, so it cannot fetch the schema from the /director/graphql endpoint as it's secured. We have figure out how to handle it, eg. adding a sidecar which would modify the request to include the authorisation headers or adding some kind of a parameter to pass when generating the files

  • Change the generated requests to our examples

We want to utilise the example requests generated during our end to end tests. We have to change the logic to use our example files instead of these generated by dociql

Apart from that we would have to maintain the config file. We would have to group every query and mutation by ourselves. Also with every change to our schema we would have to change the config file too. It would be difficult to keep the file up to date so we would probably have to figure out how to generate the config out of our examples. Other problem with config is that we have to specify the server where the example request is send to. We have to figure out how to inject the current host address of the director into the config.

Work that has to be done

  • handling the authentication
  • generating the config file
  • creating a prow pipeline
  • configuring the 'try it now' feature

Pros

  • looks pretty without modifications (example here)

Cons

  • requires much more work than the first solution
  • has to be maintained

Decision

The decision made by the team is that we will implement the first option, and maybe in the future we will add more features to it. Right now it will still improve the newcomer experience.

The second option was rejected due to the high effort to customize the tools to our needs.