Integration with Postman (or similar) for interactive API documentation

How can Hugo be integrated with Postman (or a similar API platform, like Apiary, etc.) to provide interactive documentation – defined by Apiary “as an interactive representation of your API Description for you to not only read and write, but to be a place where you can interact with your API”.

The platform needs to allow users to authenticate with our product server, generate bearer tokens, etc.

Which integrations with Hugo are available? Can anyone provide links to Hugo sites with interactive API documentation?

Thank you.

Hugo is not the right tool for this, you should probably look into swagger or something similar.

Good luck

Thanks for the feedback. I understand that Hugo itself is not the right tool. But can it be integrated with another tool like swagger or Postman?

You can do whatever you want with hugo as long as you know how to accomplish it, just don’t expect to find plugins that will magically do it for you.

Its all html, css and js at the end of the day. Can it be done in hugo? Sure, will it be easy?

That depends on your skillset and the complexity of what you want to accomplish.

Again, there’s better alternatives to accomplish what you need it’s up to you how you proceed, I’m not trying to change your mind simply trying to save you time.

Good luck

Sure, understood. A third-party company built our docs platform and turned it over to us. My own and my company’s experience with Hugo internals is quite limited, and I certainly do not have any preconceived notions about the right way to proceed (whether by plugin, integration, etc.) except that some kind of link to the main (non-API) documentation is required. So if someone has already done this, I’m happy to imitate their implementation. Thanks for your feedback!

Do you know what was used to build your docs?

That might provide some info to see what would be the best way to approach what you need.

It indeed looks like Swagger, in some form.

First, here’s a partial screenshot from the API rendering:

When you click “Authorize” you see this:

Hugo API rendering 2

There are also signs of Swagger in the Hugo file system. I’ll try to list everything I see that could be related to API definition and rendering.

Content files:

  • static / openapi – contains various .json files (one for each documentation version)
  • content / en / [folders for each documentation version] / API Reference / [folders for each API documentation section] – each contains:
    – _index.md (with header, description, and weight metadata)
    – one md file for each endpoint, containing a title and this text between double curly braces (i.e., shortcode): openapi src=“”

Files related to Hugo processing (shortcode, etc.):

  • themes/zdoc/assets/js/shortcodes/openapi.js – 160 lines long; these lines (and possibly others) mention openapi and/or swagger:

– url: location.origin + “/openapi/aqua_swagger_” + version + “.json”, //divo[i].getAttribute(‘openapi-url’),//"https://api.swaggerhub.com/apis/bokimilinkovic9/aqua-enterprise_api_overview4/1.0.0/“,//https://petstore.swagger.io/v2/swagger.json”,
– let divi = document.getElementsByClassName(‘sc-openapi-iframe’);

  • data/themeParams.toml has these lines, among others:

[includes]
[includes.shortcodes.jsModules]
openapi = [
“js/shortcodes/openapi.js”,
]
[includes.shortcodes.js]
openapi = [
“js/external/dist/swagger-ui-bundle.js”,
“js/external/dist/swagger-ui-standalone-preset.js”
]
[includes.shortcodes.css]
openapi = [
“css/external/swagger-ui.min.css”
]

  • layouts/shortocdes/openapi.html – entire contents:
{{.Page.Scratch.Add "openapiUid" 1}} {{with (.Get "id")}} {{$.Scratch.Set "openapiId" (replace . "'" "")}} {{else}} {{$.Scratch.Set "openapiId" (printf "%s%s" "openapi-" (string (.Page.Scratch.Get "openapiUid")))}} {{end}}
{{partial "theme/loading.html" .}}

Well, the good news is it looks like it is swagger but I’m not sure if it’s something custom they did with Hugo and swagger since the number of swagger assets being loaded seems concerning.

Swagger already supports auth you just need to make sure it is setup with your auth provider, more info on that can be found in the swagger docs

Hugo is highly customizable which is both good and bad, good in terms of you are limited based on your knowledge but bad in terms of where everyone can do things differently and there’s no real 100% way to do things.

So the whole there’s a 100 ways to skin a cat applies to hugo where things can be accomplished by many different means and still get the same result.

You are going to have a hard time getting advice if we can’t see your source files in order to get a better understanding of what you inherited from the third party or if they did not provide you with any docs or a flowchart of what they built and what was used.

1 Like

I could share the relevant source files. I’d need to know which files are relevant, and how/where to share them directly with you or anyone who would need to see them; I will message you privately with my contact information.

And yes, you hit the nail on the head with “they did not provide you with any docs or a flowchart of what they built and what was used”. We asked for this several times, and didn’t get it. So we’ve had to reverse-engineer a few other things, but have not tried to tackle this one yet.

Then I would recommend you share a link to the github repo where your source files are and we can check it out.

I’m afraid I can’t do that. The HTML doc portal is available only to people with licenses, and the source itself is in a company-internal Git repo, not available to the public. So the most I can do (without NDA, anyway) would be to share the subset that would be sufficient for resolving this issue.

Yeah, then it’s going to be very difficult to provide any guidance if you don’t know what the 3rd party did on their end in order to accomplish what you need.

Right now it’s hard to know if they actually are running swagger or if they did some Hugo customization to make it look like swagger.

The best thing to do at this point is to check if you see anything resembling this repoo](GitHub - swagger-api/swagger-ui: Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.) in yours to know if they are using swagger hub or something else.

Good luck