Creating static HTML Swagger API Documentation

Creating beautiful and fast API documentation can be the make or break in getting users on your platform and using your API. Today we are going to run through a full guide on creating a static HTML website to host your Swagger API documentation using squido.

To save time, we are going to use squido Swagger template.

1. Install squido using:

$ npm i -g https://github.com/mrvautin/squido.git

2. Lets clone our demo blog repo to get you started quickly:

$ git clone https://github.com/mrvautin/squido-blog-example my-swagger-docs

3. Enter the new directory:

$ cd my-swagger-docs

4. Run the following command to build, clean, serve and watch for changes:

$ squido serve -b -w -c

5. You can then visit your new website here:

http://localhost:4965

6. Create your first post: /source/posts/api-docs.markdown

---
title: Swagger API docs
permalink: swagger-api
description: This is my applications Swagger API docs
date: '2021-09-02 01:59:00'
template: swagger.hbs
visible: false
hidden: false
---

Note we set the template to swagger.hbs which is our starter Swagger template.

8. Enter the source directory:

$ cd source

9. Lets grab the swagger.hbs file:

wget https://raw.githubusercontent.com/mrvautin/squido/main/source/swagger.hbs

10. Copy your swagger.yaml or swagger.json into your source directory. If you don't have one yet, you can grab our demo one:

wget https://raw.githubusercontent.com/mrvautin/squido/main/source/swagger.yaml

11. Edit your config.js to turn on the Swagger file parsing:

const config = {
  development: {
    name: 'squido',
    description: 'This is the blog description',
    twitterHandle: '@mrvautin',
    baseUrl: 'http://localhost:4965',
    sourcesExt: 'markdown',
    templateEngine: 'hbs',
    data: [
      {
        name: 'swagger',
        type: 'yaml',
        file: 'swagger.yaml'
      }
    ],
    sourceDir: 'source',
    buildDir: 'build',
    ...
  }
}

Note the data section. See here for more options.

12. You can now visit your static HTML Swagger API docs by visiting here:

http://localhost:4965/swagger-api

BOOM!! static HTML Swagger API docs! Now you can go ahead and add any changes, start styling and away you go. Notice the speed of the docs. That's the power of Static HTML!

You can follow the squido documentation to customize your website and once you are ready, you can host using our deployment guides here.