Hello thedevsaddam,

I'm having a weird issue after generating an index.html file for my API. If I run it directly then it works perfectly fine without any errors but if I run it in my NodeJS-Express app (as shown in an udemy course) it throws an error in the dev console after clicking on the collapsed state of the endpoints. What could be the issue?

I tried running this on a windows machine:
docgen build -i dc.postman-collection.json -o ~/Downloads/index.html

And I got this error:

'''
fs.js:45
} = primordials;
^

ReferenceError: primordials is not defined
←[90m at fs.js:45:5←[39m
at req_ (C:\Users\Owner\AppData\Roaming\npm\node_modules\←[4mdocgen-tool←[24m\node_modules\←[4mnatives←[24m\index.js:143:24)
at Object.req [as require] (C:\Users\Owner\AppData\Roaming\npm\node_modules\←[4mdocgen-tool←[24m\node_modules\←[4mnatives←[24m\index.js:55:10)
at Object. (C:\Users\Owner\AppData\Roaming\npm\node_modules\←[4mdocgen-tool←[24m\node_modules\←[4mgraceful-fs←[24m\fs.js:1:37)
←[90m at Module._compile (internal/modules/cjs/loader.js:1072:14)←[39m
←[90m at Object.Module._extensions..js (internal/modules/cjs/loader.js:1101:10)←[39m
←[90m at Module.load (internal/modules/cjs/loader.js:937:32)←[39m
←[90m at Function.Module._load (internal/modules/cjs/loader.js:778:12)←[39m
←[90m at Module.require (internal/modules/cjs/loader.js:961:19)←[39m
←[90m at require (internal/modules/cjs/helpers.js:92:18)←[39m
'''

Anyone knows how to deal with this?

If you add a path variable into the URL by adding :variable then describe it in Postman it is not shown in the documentation.

By adding this into Postman the JSON has an additional "path" parameter which maps to a "key" inside the "variable" array:

  "url": {
    "raw": "{{url}}/logs/:schedule_id",
    "host": [
      "{{url}}"
    ],
    "path": [
      "logs",
      ":schedule_id"
    ],
    "variable": [
      {
        "key": "schedule_id",
        "value": "2",
        "description": "ID of the Schedule"
      }
    ]
  }

Is it possible to get this added in?

Thanks

I noticed that the list ordering differs from Postman. Postman respects the order in which you wrote things down.

If I have a list that says:

1. Login.json
2. Validate.json
3. GetUserInfo.json

docgen will generate this to be in order: 3-1-2.

There is, however, a clear reason I put those documents in that specific order. It should not be changed.

Looking at the code:

and

This behavior is hardcoded and I think it should configurable.

I've tested with a simple json file coming from Postman.
The different sections/functions are present, but the parameters of calls are not present in your HTML export.
I've verified, they are in the json file.
I'm using the windows version.
Is there is any known issue ?
Thanks

Hello!
First of all,I would like to thank you for having developping this tool.

Here is the issue:

I have a postman collection with few subfolders such as

{
	"info": {
		"_postman_id": "",
		"name": "",
		"description": "",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "v1",
			"item": [
				{
					"name": "1. title",
					"item": [
						{
							"name": "1.2. title",
							"item": [
								{
									"name": "1.2.1. title",
									"item": [
										{
											"name": "1.2.1.1. title",
											"event": [...],
											"request": {...},
											"response": []
										},
...

When generating the HTML documentation from this collection, it generates only the first and second level of items.

Example:

Thanks for your help.

Hi!

I am trying to build a docker image for your tool, based on the Alpine image. Is it possible to release an Linux arm build?

Thanks in advance!

After building new documentation and inspect the HTML file, the console shows 3 missing file error:

Hi all,
Is it possible to leave the response html body as highlighted Html code instead of html character entities? It's impossible to read now.

Here is how it looks in postman:

And here's docgen output:

Thanks a lot and stay safe and healthy.

Pavol

I currently have a pretty large collection (600+ requests), neatly organized in sub folders, nested between 3 for 5 deep.

When trying to build or view the collection, the generation says that it's successful, but the nested trees end up empty:

Unfortunately, I cannot share the postman collection, but if necessary, I may be able to reproduce it in a contrived manner.

When i try to build the json file from postman on UBUNTU 18.04, using this ==> brew docgen build -i DevCamperAPI.json -o index.html
It throws this ==> Error: Unknown command: docgen

Please help.

Postman can use {{ }} to set environment variables,
For example: I can turn {{url}}/dosomethingapi into https://example.domain/dosomethingapi,
But the current version does not support this feature, I hope to add this feature, it can use docgen build -i input-postman-collection.json -o ~/Downloads/doc.html -e ~/Downloads/postman_environment.json

• I was wondering if anyone had created a GitHub Action based on docgen.
• That would permit to easily integrate docgen within Github Action workflows (piping the step into GitHub pages, or publication to servers, or whatever)

I want to run docgen on Windows. README.md says to get the binary, but it is not up-to-date with the master, and I want to get the latest checkins.

I ran the installation command per README.md, but it gives an error:

C:\Users\cstreb\go\src>go get -u github.com/thedevsaddam/docgen
# github.com/thedevsaddam/docgen
github.com\thedevsaddam\docgen\funcmap.go:17:13: undefined: AssetFS

I downloaded and unzipped the zip file to a different folder, opened a cmd window there, and tried this which fails with the same error:

C:\Users\cstreb\go\src\docgen-2-20190809>go build -o ..\docgen.exe
# docgen-2-20190809
.\funcmap.go:17:13: undefined: AssetFS

I also went up a level and tried the following, but still get the same error:

C:\Users\cstreb\go\src>go build docgen-2-20190809
# docgen-2-20190809
docgen-2-20190809\funcmap.go:17:13: undefined: AssetFS

Sorry, I do not know go. Am I missing something?

How to uninstall docgen from linux ?

Gitlab seems to have slightly different rules for how it escapes spaces for it's anchor links: https://docs.gitlab.com/ee/user/markdown.html#header-ids-and-links

This causes the links generated for the index/TOC, to not work when a string has a hyphen surrounded by spaces e.g "/api/example - success"

Docgen will make a link such as: [/api/example - success](#apiexample-success)

However Gitlab will create an anchor ID such as: id=apiexample---success

I tried to look at the function that generates links, but I can't seem to find the source of the function:

I don't know what the right answer to this problem is, since changing the behavior will have a breaking effect for Markdown pages rendered by Github or Chrome where they seem to have slightly different behavior for the anchor tag links (header IDs). Maybe we can have a "gitlab" flag that allows the links to be generated/escaped using the same rules Gitlab follows?

great job !
it work good with postman collection 2.1.
i found it may not support postman collection1 and collection 2 .
and i found a problem. when the api info included Chinese word, the html file work wrong. it show the first api detail no matter which api you click in that list.
do you have the plan to add Chinese support? i hope i can help this.
thank you again for your job.

If we generate a Markdown or HTML file from a Postman collection, the requests directly in the collection (outside any subfolder) are reversed.

For example, with the following collection:

{
	"info": {
		"_postman_id": "72a750d2-5658-4e2f-a475-3317b4c7ec73",
		"name": "Test collection (requests order bug)",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "first",
			"request": {
				"method": "GET",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": ""
				},
				"url": {
					"raw": ""
				}
			},
			"response": []
		},
		{
			"name": "second",
			"request": {
				"method": "GET",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": ""
				},
				"url": {
					"raw": ""
				}
			},
			"response": []
		},
		{
			"name": "third",
			"request": {
				"method": "GET",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": ""
				},
				"url": {
					"raw": ""
				}
			},
			"response": []
		}
	]
}

We get the following html:

when .json is too heavy, and converting will take n hours. So should be warn o throw an exception.
A more sotisficated strategy may cut too large body or examples.

Hello!

Your contribution guidelines say:

It should pass all tests in the available continuous integrations systems such as TravisCI

But docgen doesn't appear to be set up in Travis-- is that something you still plan on doing?

Does not document GraphQL body

some markdown format is accepted by postman but not work when it is transformed to html.
here is some examples:

出参说明\r\n\r\n|参数名称|参数说明|\r\n|--------|--------|\r\n|infoid|资讯id，用于获取资讯详情|\r\n|title|资讯标题|\r\n|author|作者|\r\n|publishdate|发布时间|\r\n|status|资讯状态，2：已发布|

in old version, I find postman can accept \r\n or \n, but docgen can only accept \n.
I am not sure whether it is the same in version 3

• add feature pathname in ther server

Documentation is not generating for the nested folders.

Minor improvements to the section headers and wording would simplify the markdown document and improve readability. See the example here: #29

I get this unsolvable error in the console and the menus don't work
Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self'". Either the 'unsafe-inline' keyword, a hash ('sha256-ZomnyosL2bmZ79LmErHEhL+1fVaBj9NngvpOK/l4qio='), or a nonce ('nonce-...') is required to enable inline execution.

Have a look at my website and see >> https://woofer-api.herokuapp.com/
GitHub >> https://github.com/silvertechguy/woofer-api/blob/master/server.js

I'm so sorry for my terrible English

Hi, in order to spread the tool over enterprise suite software should be removed github sign.
Usually there re not time to change code or create a script workaround, and tend to be a first signal to deny.

First off, this is a great little tool. I love it!

The "examples" for a request do not include the request body for each response example. I see how I can work around it by creating a new top-level request for each example, but it seems to clutter the interface in Postman by having to create a lot of requests for each API, rather than using the examples concept that seems to solve that problem quite nicely. I'm happy to reorganize my requests and APIs, but I'm curious if there's a way to have an optional flag to also include the request body for each example?

My API folders and routes in Postman:

An example request/response in Postman:

The resulting markdown without the request body:

Thanks!

点击无法跳转到对应的接口中
我查看md文件是因为生成（#headerid）没有处理中文

Hi,

I installed the latest windows_amd64.exe as explained in the readme.

• Also added the binary as env. variable

• Rebooted pc

But when trying to run docgen server -f API.postman_collection.json -p 8000, I receive the error message:

'docgen' is not recognized as an internal or external command, operable program or batch file.

Any idea if there are extra steps to perform?

Kind regards,
Job

I was wondering if support for sample code of sending requests in different languages (ex. Python, Java...) would be possible

For example, each request would have a dropdown or something with options for different languages. For example, the Python language would be like so:

import requests
import json

url = "http://localhost:8080/"

payload = json.dumps({
    "some_key": "some_value"
})
headers = {
    'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Just like the code examples available in Postman

When using the latest version of docgen I got trouble with generating markdown for request that is included inside a map that is inside another map:

• Profile-service (map)
  • business controller (map)
    • request 1
    • request 2
  • invite controller (map)
    etc.

This used to work but now it does not. Did something change?

I use

curl https://raw.githubusercontent.com/thedevsaddam/docgen/v3/install.sh -o install.sh \                                                                                                       
&& sudo chmod +x install.sh \
&& sudo ./install.sh \
&& rm install.sh

Then the command line shows

Found docgen latest version:
Download may take few minutes depending on your internet speed
Downloading docgen to /usr/local/bin/docgen
Installing docgen
Installation complete
./install.sh: line 29: docgen: command not found

Unable to install successfully, what is the reason？

On win 11, collection V2, docgen 3.3.0 I get:

2022/10/02 15:39:48 parsing json filejson: cannot unmarshal string into Go struct field Request.item.item.request.url of type collection.URL

Exported my Node API calls from Postman then used Docgen to generate my index.html file then copied to the root of my public folder. When I view the html file via my node server in the browser I am getting a console errors. The first error complained about the favicon.ico so I copied one to the public folder which removed the error. I am unable to remove the CSP error after trying suggested methods in the error using Helmet middleware options.

If open html file directly with the browser I don't get the CSP error so it only happens when I accessing the file via Node API server root. Please advice, full error listed below.

Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self'". Either the 'unsafe-inline' keyword, a hash ('sha256-ZomnyosL2bmZ79LmErHEhL+1fVaBj9NngvpOK/l4qio='), or a nonce ('nonce-...') is required to enable inline execution.

Hi, I have downloaded the windows_amd64.exe binary file and setup the docgen environment variable.
running echo %docgen% build -i input-postman-collection.json -o ~/Downloads/index.html from the command line does
nothing however. Could this be anti-virus protection coming from windows. I would appreciate your help as this feature is very cool. Thanks

The links generated at the top of a markdown document that link to each request and request example, don't seem to format the header ID the same way markdown converters do. e.g. they do not strip out parenthesis or "="

My Header (var=true)

My Header (var=true)

I've tested the generated markdown in Gitlab and a markdown plugin for Chrome and see the same results. I'm not sure if Github generates anchor IDs differently (I added the example above to check). Here's the Gitlab documentation showing how IDs for headers with parenthesis are generated: https://docs.gitlab.com/ee/user/markdown.html#header-ids-and-links

I have a Postman project (Test collection.postman_collection.txt) which contains two GET requests, returning JSON-parsed informations, and a PUT request, which get informations as raw text in the request body.

When loading the docgen-generated HTML file, the page seems to try to pretty-print the body raw text, as a JSON string, as you can see with this exception:

"SyntaxError: Unexpected token a in JSON at position 0
    at JSON.parse (<anonymous>)
    at HTMLSpanElement.<anonymous> (http://localhost:8001/:384:22)
    at Function.each (http://localhost:8001/:344:2881)
    at n.fn.init.each (http://localhost:8001/:344:846)
    at HTMLDocument.<anonymous> (http://localhost:8001/:370:32)
    at i (http://localhost:8001/:344:27449)
    at Object.fireWith [as resolveWith] (http://localhost:8001/:344:28213)
    at Function.ready (http://localhost:8001/:344:30006)
    at HTMLDocument.K (http://localhost:8001/:344:30368)"

With the browser debugger, we can see the raw text failed to be pretty-printed:

This gives the following:

As you can see, the PUT request body isn't display, and the JSON strings after this request are not pretty-printed.

Hi, may I request to add Bearer Token is required at any area of the html docgen if the API is needed Bearer Token to proceed. Thank you so much and appreciate your help.

Response examples don't include headers in reply. This is actually needed in some environment where response headers are used as out-of-band information.

Hi all,

First of all, thanks for developing such a nice tool.

I am using greater than and less than characters in my collections to wrap variables. However, in HTML output it does not display the greater/less than characters, and the text between them.

I have replaced the greater/less than characters with ">/<" in the JSON of the collections to have an acceptable result for the HTML output.

It would be nice to support these characters by default for the HTML output.

Thanks

Hi thedevsaddam,

When building an html file, the side nav menu stays on top of the page.
Is it possible to have the side menu scroll along with the page?
So the user shouldn't scroll to the top to reach the menu.

Kind regards,
Job

HTML conversion works but Markdown conversion hangs:

docgen build -i off-pm-collection.json -e off-net-env.json -o index.md -m

From this repo: https://github.com/openfoodfacts/api-documentation

I manually killed it after 20mn.

Have you seen this ?

2020/11/17 21:24:17 parsing json filejson: cannot unmarshal string into Go struct field Request.url of type collection.URL

I downloaded the latest version v3.0.0-rc2 and encountered some errors.

1. When I use the -s in the command line, I receive the following error: "Error: unknown shorthand flag: 's' in -s"

2. If I remove the -s, and run the command line "docgen build -i postman_collection.json -o index.html", I get the following error: "2020/05/29 11:45:28 parsing json filejson: cannot unmarshal object into Go struct field Field.item.item.item.item.response.originalRequest.body.formdata.description of type string"

Both of these items worked on the previous version.

Would be great to have a 'Run' button under each request to run the request live and see the response (like examples but with a live response).

Background

I wanted to run the the built in server. But I need to add 10 lines of css code and adjust the appearances. I would be nice to have such feature that would add additional css into the server or maybe in the build as well.

Current Command

docgen server -f input-postman-collection.json -p 8000

Proposed Command

docgen server -f input-postman-collection.json -c style.css -p 8000

I have downloaded windows_amd64.exe but when I run it, it flashes for seconds with this message "u need to open cmd and run it from there" and when i run it with cmd, it still opens, flashes and closes itself. Any help?

When Postman exports a collection to json, it includes the response objects. When that is run through DocGen, if the response body includes the characters < and >, it is returning some weird behavior. For instance:

As you can see, it added < /integer >< /integer > to the end.
If the response body includes < object >, it kills the rest of the document:

Here, it dropped the word "Body", and then attached the remainder of the document to the end of the "Body" section. If I manually replace < object > with < string >, then it returns to the behavior listed above.