loading...
Cover image for Express Autodocs - A GitHub Action to generate documentation (Submission)

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

pika1998 profile image Prafulla Raichurkar Updated on ・2 min read

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

GitHub logo Pika1998 / 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


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
      - 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

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:
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.

Posted on by:

pika1998 profile

Prafulla Raichurkar

@pika1998

Developer. 21 y/o IT Engineering Student

Discussion

pic
Editor guide
 

That's interesting!

 

Thank you 😃

 
 

Thank you 😁✨

 

This is cool 🎉 ! You can see mine 😄

 

Sure, even yours seems cool 😁