thedevsaddam / docgen Goto Github PK
View Code? Open in Web Editor NEWTransform your postman collection to HTML/Markdown documentation
License: MIT License
Transform your postman collection to HTML/Markdown documentation
License: MIT License
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
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?
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!
I downloaded the latest version v3.0.0-rc2 and encountered some errors.
When I use the -s in the command line, I receive the following error: "Error: unknown shorthand flag: 's' in -s"
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.
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
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.
Documentation is not generating for the nested folders.
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 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:
This used to work but now it does not. Did something change?
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:
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:
docgen/collection/collection.go
Line 112 in 517f663
and
docgen/collection/collection.go
Line 167 in 517f663
This behavior is hardcoded and I think it should configurable.
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
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 ?
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.
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 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
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
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 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.
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 "="
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
Does not document GraphQL body
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.
docgen server -f input-postman-collection.json -p 8000
docgen server -f input-postman-collection.json -c style.css -p 8000
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.
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
2020/11/17 21:24:17 parsing json filejson: cannot unmarshal string into Go struct field Request.url of type collection.URL
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.
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
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?
How to uninstall docgen from linux ?
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.
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.
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
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?
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
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:
Line 223 in 7c09b00
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?
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!
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.
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).
Minor improvements to the section headers and wording would simplify the markdown document and improve readability. See the example here: #29
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.
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?
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:
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.