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
โฆ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
Top comments (6)
That's interesting!
Thank you ๐
So cool!๐ฅ
Thank you ๐โจ
This is cool ๐ ! You can see mine ๐
Sure, even yours seems cool ๐