DEV Community

Cover image for Express Autodocs - A GitHub Action to generate documentation (Submission)
Prafulla Raichurkar
Prafulla Raichurkar

Posted on • Updated on

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

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 }}"
Enter fullscreen mode Exit fullscreen mode

For a detailed configuration, checkout the official repository

GitHub logo prafulla-codes / express-autodocs

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



Contributions


๐Ÿ’ก Introduction

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

Whats New?

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
โ€ฆ
Enter fullscreen mode Exit fullscreen mode

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);
    });
});
Enter fullscreen mode Exit fullscreen mode

Output Format

Supports two output formats markdown and standard
Default output example:
Output 1

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

๐Ÿ’–๐Ÿ‘จโ€๐Ÿ’ป It was fun and enlightening to participate in the actions hackathon.

Top comments (6)

Collapse
 
mikitashah profile image
mikitashah

That's interesting!

Collapse
 
prafulla-codes profile image
Prafulla Raichurkar

Thank you ๐Ÿ˜ƒ

Collapse
 
singhshivani profile image
Shivani Singh

So cool!๐Ÿ’ฅ

Collapse
 
prafulla-codes profile image
Prafulla Raichurkar

Thank you ๐Ÿ˜โœจ

Collapse
 
shunjid profile image
Shunjid Rahman Showrov

This is cool ๐ŸŽ‰ ! You can see mine ๐Ÿ˜„

Collapse
 
prafulla-codes profile image
Prafulla Raichurkar

Sure, even yours seems cool ๐Ÿ˜