Kong Dev Portal comes out of the box with a RESTful API-based catalog and YAML-based template functionality. In this tutorial, I'll show you how to get to the next level of API documentation using Kong Dev Portal with GraphQL. That way, you'll be able to give your API developers an interactive experience.
In my example, I'll be using Kong Konnect Enterprise Version 2.4, but the version number does not really matter. I also configured my workspace with one service that points to a Star Wars API endpoint with a GraphQL interface (swapi-graphql.netlify.com).
We'll also be using an open source tool called GraphiQL for interactive documentation of a GraphQL endpoint. With GraphiQL, we'll see requests, responses and automated generation of documentation based on the endpoint.
Let's get started.
Since we're starting from scratch, we'll first need to create our template or use one of the layouts that come with Kong out of the box.
Click New File +. Select theme as the file type. We'll enter base/layouts/graphql.html as the file pathname. Right now, this is a very lightweight template. Click Create File.
To add to it, we can include a header and footer by borrowing from what we already have in the graphql.html file we just created. But, for now, we'll just add an H1 that says “Hello World.”
Now that we have a template, we need to set up a system that will use it. We need to have content which references this template. Let’s create that file just as we did in the previous step. Change File Type to content. Change the File Path to swapi/index.md. Click Create File.
Edit the file as below and Save Changes:
Now that we have a template rendered, let's make our title visible on the Dev Portal. In our template, we can embed any data in that YAML file we edited earlier. Now it’s rendering "Star Wars" as the title.
Upload the content here and say it’s now about “May the 4th.” We are getting dynamic rendering of content here, and you can put anything in that YAML structure.
Let’s go ahead and let’s add a URL. And we will take the URL out of the already existing backend. I’ve already proxied it here using Kong. The URL of our Star Wars API backend is http://localhost:8000/swapi.
So far, we've been entering data. We could display the URL by adding it to the graphql.html file.
GraphiQL is a JavaScript interface. In Kong, you can use any language in the templates, including HTML, CSS and JavaScript.
From GraphiQL's GitHub, we can copy and paste an example into our template. Change the API URL to the one we set earlier (http://localhost:8000/swapi). Save Changes. Now we have a working GraphQL within our browser.
Before we look at how this renders in the real world, let's change the hardcoding to a variable. We created a variable for that earlier, so we can just put it in here.
This time, I will not use the two curly brackets. This time, I will use a slightly different syntax. The reason for that is that we do not want to encode this in some ways. We all want to have the full URL available in JavaScript. We have many options to parse our data. Let's use page.url like we have done before. Save Changes. It’s now rendering as expected.
Now we have a running version of GraphQL at localhost:8003/swapi. There are some minor quirks, which we can make nicer, but it’s already fully working.
If we press ▶, we get a response back from the backend system. This portal is a lovely interactive way to work with an API. Everything is pulling from the backend system. We get autocomplete, multivariable and other bells and whistles from the nice graphical endpoint. We got all of this by just copying some JavaScript and HTML into a template. And now we can put as many pages based on that into the system.
At this point, there's no link to this interactive Dev Portal, so no one can find it. Everything in Kong Dev Portal is declarative, including the navigation. We can change this in the menu structure in our YAML file. You can do much more fancy things, like authentication and role-based access control. Just for this example, adding navigation is enough.
Once we reload our Dev Portal, we have another endpoint to get to our interactive Star Wars API documentation. Or you could create an overview page where we list all of them. The opportunities are endless.
This example is just a high-level overview of how much we could do using Kong Dev Portal with GraphQL. We just created an interactive tool that does JavaScript and autocompletes with just a few snippets and the template Kong provides. Kong automates everything else.
Start a free trial, or contact us if you have any questions as you're getting set up.
Once you've set up Kong Dev Portal with GraphQL, you may find these other tutorials helpful:
In this blog post, we'll talk about the significant challenge of managing and governing a growing number of APIs across multiple teams in an organization — and how Control Plane Groups are a clear solution to avoid the chaos of inconsistent policies
Meet Emily. She’s an API product manager at ACME, Inc., an ecommerce company that runs on dozens of APIs. One morning, her team lead asks a simple question: “Who’s our top API consumer, and which of your APIs are causing the most issues right now?”
The healthcare industry is buzzing about FHIR (Fast Healthcare Interoperability Resources). Pronounced “fire,” this widely adopted data standard has been revolutionizing how healthcare information is exchanged. But building a truly modern, secure, a
Behind every smooth user experience is a maze of APIs quietly handling requests, responses, and data flows. This makes APIs critical connectors that enable applications to communicate and share data seamlessly. When these vital conduits fail, the
Organizations are going all-in on large language models (LLMs), with research finding 72% anticipate increased LLM spending in the coming year (and about 40% are already investing more than $250,000 USD per year). As enterprises rapidly adopt LLMs
In the last two parts of this series, we discussed How to Strengthen a ReAct AI Agent with Kong AI Gateway and How to Build a Single-LLM AI Agent with Kong AI Gateway and LangGraph . In this third and final part, we're going to evolve the AI Agen
In my previous post, we discussed how we can implement a basic AI Agent with Kong AI Gateway. In part two of this series, we're going to review LangGraph fundamentals, rewrite the AI Agent and explore how Kong AI Gateway can be used to protect an LLM
