Create account

DEV Community

Prafulla Raichurkar

Posted on Sep 7, 2020 • Updated on Sep 11, 2020

Express Autodocs - A GitHub Action to generate documentation (Submission)

#actionshackathon #showdev #opensource #javascript

I am glad to announce my submission to the GitHub Actions Hackathon 😄

Are you tired of maintaining documentation for your APIs?

Express AutoDocs is a GitHub action that solves this problem.

Submission Category:

Maintainer Must-Haves

My Workflow

Express AutoDocs scans your codebase for express API definitions and automatically generates the documentation and deploys it to a GitHub branch.

Example Repo - MERN_SHOPPINGLIST

YAML File

Here's how you can integrate Express AutoDocs in your workflow.

# This is a basic workflow to help you get started with Express AutoDocs Action

name: Express AutoDocs.

# This specifies when the action should occur
on:
  push:
    branches: [master]

jobs:
  generate_docs_job:
    runs-on: ubuntu-latest
    name: Generating Docs
    steps:
      # this step checks out the master branch of your repo using checkout action.
      - name: Checks out the repository
        id: checksout-repository
        uses: actions/checkout@v2
        with:
          repository: ""
      # this step generates the docs
      - name: Generating Docs.
        id: reading-file
        uses: Pika1998/express-autodocs@v0.0.1
      # Use the output from the `hello` step
      - name: Get the output time
        run: echo "The time was ${{ steps.reading-file.outputs.time }}"

For a detailed configuration, checkout the official repository

prafulla-codes / express-autodocs

A GitHub action which automatically generates documentation for your express APIs.

💡 Introduction

This action automatically scans for express APIs in your codebase and generates a documentation website

Whats New?

Added JSDOC Like Syntax to define APIs (Thanks to @rahil1304)
Refactored Code & Reduced Bugs (Thanks to @rosborne132 & @KulkarniSuraj)
Added Unit Tests

How to add to your workflow ❔

To add this action to your workflow simply modify your workflows main.yml file.

# This is a basic workflow to help you get started with Express AutoDocs Action
name: Express AutoDocs.

# This specifies when the action should occur
on:
  push:
    branches: [master]

jobs:
  generate_docs_job:
    runs-on: ubuntu-latest
    name: Generating Docs
    steps:
      # this step checks out the master branch of your repo using checkout action.
      - name: Checks out the repository
        id: checksout-repository
        uses: actions/checkout@v2
        with:
          repository: ''
      # this step generates the docs

…

View on GitHub

Additional Info

Easily Pass API Info using JSON in comments
Example

/*  
{
    "description":"Checks for token and gets the logged in user",
    "inputs":{
        "x-auth-token":"The JWT Token in header"
    },
    "label":"Public",
    "outputs":{
        "user":"The user object stored in database",
    }
}
*/
router.get("/user", auth, (req, res) => {
  User.findById(req.user.id)
    .select("-password")
    .then((user) => {
      res.json(user);
    });
});

Output Format

Supports two output formats markdown and standard
Default output example:

Easy CI/CD Integration

It is very easy to maintain the documentation website since the action deploys the output to a GitHub branch which can be easily set up as a deployment branch using Github pages, Netlify, etc.

Checkout on GitHub MarketPlace