hoppscotch/hopp-doc-gen

📔 API documentation generator CLI for https://hoppscotch.io

Hopp Doc Gen

An API documentation generator CLI by https://hoppscotch.io

---

Installation

$ npm install -g hdg

Or, with npx

$ npx hdg generate <path>

Usage

Usage: hdg <command> [options]

An API documentation generator CLI

Options:
  -V, --version              output the version number
  -h, --help                 display help for command

Commands:
  generate [options] <path>  Generate API Documentation
  help [command]             display help for command

Generate API Doc

Usage: hdg generate [options] <path>

Generate API Documentation

Options:
  -s, --skip-install        skip installation of vuepress and just create the markdown file
  -o, --output-path <path>  specify an output path (default: "docs")
  -r, --request-buttons     add a request button for each GET request
  -h, --help                display help for command

path - path to hoppscotch-collection.json exported from hoppscotch.io

Contributing Guidelines

• Clone the repository.
• Navigate to the directory and install dependencies with npm install.
• Now fire in npm link which creates a symlink and now hdg can be accessed globally.

Instructions

Hopp Doc Gen generates documentation (using Vuepress) based on Hoppscotch collections.

1. Navigate to https://hoppscotch.io/doc and export a collection. (by clicking on the Import/Export button in the Collections pane).

2. Then generate documentation using the following command:

$ npx hdg generate hoppscotch-collection.json

3. To preview your generated documentation, run

$ npm run docs:dev

4. Deploying to Netlify!!!

Once you feel like you're ready to publish the documentation, you can deploy it on Netlify.

To deploy your documentation to Netlify, you'll have to build the files first.

$ npm run docs:build

5. At this point, you need to create a GitHub repo to deploy your documentation on Netlify. So create a GitHub repo and give it an awesome name!

6. Then, push the documentation folder to your GitHub repo.

$ git remote add origin https://github.com/USERNAME/NAME_OF_REPO_WHERE_DOCUMENTATION_IS_TO_BE_DEPLOYED
$ git add .
$ git commit -m "generate api doc"
$ git push -u origin master

7. Once you're logged in at https://netlify.com, create a new site by clicking on New Site from Git. Choose your Git provider and then choose your awesome repo where the awesome documentation is located!

8. Under the Basic Build Settings, set build command as npm run docs:build and set the publish directory as docs/.vuepress/dist.

9. And then click on Deploy Site! And hopefully, Netlify should build your documentation and make it live! 🥳

10. Congratulations, you have successfully deployed your documentation on Netlify!

hopp-doc-gen's Issues

docs is missing

add few comments to start work on that

`pw-cli generate` error

pw-cli generate <path to collection> error.

Has this project been completely abandon ?

Im currently trying out Hoppscotch, n it's pretty good but there's no built-in API documentation then i found this hoping it could help but it doesnt seem to give much help regarding API documentation. So the question being has this been completely abandon ?
(i'm sorry since this is not an actual issue but there's no disscussion tab so i have to post this here)

Add new options to generate command

Consider adding some options for the users in the generate command?

I was wondering something like:

generate <path>                 Create API documentation
generate [options] <path>

Options:
  -o, --output-path <path>       The documentation markdown file output path
  -u, --update <path>            Update de documentation markdown file
  -n, --no-install               Skip npm install and create only the markdown file
  -r, --request-buttons          Add a request button for each request

1. -o, --output-path <path>
   Now the default value of path is docs/README.md. Would be nice if we could replace it for some other path.

2. -u, --update
Now if we have a docs folder or a package.json the process is stoped. As the api evolves is common the need to update the documentation. With this option set, the user could just update the existing markdown file.

3. -n, --no-install
   It is great that the cli create all the doc website and npm install and so on. But in some cases it is more usefull to gerenerate just the plain markdown.

4. -r, --request-buttons
   Would be nice if in the generated website we could run the requests and easily test the apis.

todo:

hdg generate <options>

• -o, --output-path <path>
• update existing doc after response from the user
• -n, --no-install
• -r, --request-buttons
• tests

folders aren't parsed

collection

[
    {
      "name": "Demo",
      "folders": [
        {
          "name": "folder1",
          "requests": [
            {
              "url": "http://127.0.0.1:1984",
              "path": "/first-folder1",
              "method": "GET",
              "name": "Inside sub-folder",
              "collection": 2
            },
            {
                "url": "http://127.0.0.1:1984",
                "path": "/second-folder1",
                "method": "GET",
                "name": "Inside sub-folder",
                "collection": 2
              }
          ],
          "folders": []
        },
        {
            "name": "folder2",
            "requests": [
              {
                "url": "http://127.0.0.1:1984",
                "path": "/first-folder2",
                "method": "GET",
                "name": "Inside sub-folder",
                "collection": 2
              },
              {
                "url": "http://127.0.0.1:1984",
                "path": "/second-folder2",
                "method": "GET",
                "name": "Inside sub-folder",
                "collection": 2
              }
            ],
            "folders": []
          }
      ],
      "requests": [
        {
          "url": "http://127.0.0.1:1984",
          "path": "/outside",
          "method": "GET",
          "name": "Outside sub-folder",
          "collection": 2
        }
      ]
    }
  ]

actual output

command

hdg generate -s example.json

output

# API Documentation

## Demo
### Outside sub-folder
 - url: http://127.0.0.1:1984
 - path: /outside
 - method: GET
---

<br/>

expected output

# API Documentation

## Demo
### Outside sub-folder
 - url: http://127.0.0.1:1984
 - path: /outside
 - method: GET
---
### folder1
#### Inside sub-folder
 - url: http://127.0.0.1:1984
 - path: /first-folder1
 - method: GET
---
#### Inside sub-folder
 - url: http://127.0.0.1:1984
 - path: /second-folder1
 - method: GET
---
### folder2
#### Inside sub-folder
 - url: http://127.0.0.1:1984
 - path: /first-folder2
 - method: GET
---
#### Inside sub-folder
 - url: http://127.0.0.1:1984
 - path: /second-folder2
 - method: GET
---

<br/>

Not working

i got,
postwoman-cli>postwoman-cli get
'postwoman-cli' is not recognized as an internal or external command,
operable program or batch file.

feature: test api with postwoman-collection.json

Describe the solution you'd like
send api requests and report status based on postwoman-collection.json file

Describe alternatives you've considered
create a new command send or test to send and report the status of the requests

Aditional context

$ pw-cli send path/to/postwoman-collection.json

regres.in # collection name
┌──────────────────────────────────────────────────┬───────────────┬───────────────┐
│ url                                              │ method        │ status        │
├──────────────────────────────────────────────────┼───────────────┼───────────────┤
│ https://reqres.in/api/users                      │ GET           │ 200           │
├──────────────────────────────────────────────────┼───────────────┼───────────────┤
│ https://reqres.in/api/users/api/users            │ POST          │ 201           │
├──────────────────────────────────────────────────┼───────────────┼───────────────┤
│ https://reqres.in/api/users/api/users/999        │ GET           │ 200           │
├──────────────────────────────────────────────────┼───────────────┼───────────────┤
│ https://reqres.in/api/users/api/users/999        │ DELETE        │ 403           │
└──────────────────────────────────────────────────┴───────────────┴───────────────┘

future: could have some options to display full headers and the response body --headers --response