Building documentation websites is trivial with Swagger and Gatsby/React

Most modern applications provide API documentation in the form of a website so that third-party developers can build integrations and extensions.

Since we are using Microservice pattern here at PoweredLocal, our product consists of a bunch of small applications written in different languages. Nevertheless, creating a documentation website proved to be a trivial task!

Every of our microservices (small applications) is implementing Swagger-compliant API documentation endpoint. In other words, it can describe its own exposed controller methods using a commonly understood language (Swagger).

So, three simple steps to get a nice looking API documentation website:

  • Automatically export Swagger-compliant JSON documentation from every application, based on class/method annotations in the code;
  • Copy these files to Gatsby folders and import them in the corresponding React components;
  • That’s it — every resource now has a good looking page, rendered using a very simple React component.
Good looking API documentation based on open-source theme

You can see the result here: https://api-doc.poweredlocal.com/

And it’s open source: https://github.com/PoweredLocal/api-doc

An example of a Gatsby page/component:

import React from 'react'
import { config } from 'config'
import documentation from './swagger.json'
import Swagger from 'components/Swagger'
import DocumentTitle from 'react-document-title'
exports.data = {    
title: 'Devices'
}
const Page = (props) => (
<DocumentTitle title={`${props.route.page.data.title} | ${config.siteTitle}`}>
<Swagger documentation={documentation} prefix={config.apiUrl} />
</DocumentTitle>
)
export default Page

Load Swagger documentation from a JSON file, pass it to the component in a prop and that’s pretty much it.


About us

PoweredLocal is a Melbourne-based wi-fi innovation startup. We host PHP, Ruby and Node.js microservices behind our newly baked API gateway.

About author

Written by Denis Mysenko, Chief Technical Officer at PoweredLocal

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.