In this post, we’ll see how ChatGPT can be used to reinvigorate APIs by creating an OpenAPI specification for an existing API that has existing documentation.
ChatGPT, developed by OpenAI, has generated attention for its natural language processing capabilities. ChatGPT is based on machine learning techniques such as Generative Pre-trained Transformer (GPT) architecture which is part of Large Language Models (LLMs).
Application Programming Interfaces (APIs) underpins modern software development, enabling communication between different systems. Legacy APIs often lack standardized documentation, and versioning controls leading to outdated information, maintenance challenges, and slower API usage uptake.
Newer APIs often adopt standards such as OpenAPI specification which is defined by the OpenAPI Initiative to describe how the APIs work in machine-readable documentation. Using an OpenAPI specification to describe an API provides consistency across APIs, the ability to document the API, a contract on how to use the API, the ability to generate code stubs to consume and produce APIs, and API versioning. These features enable quicker API development, quicker uptake of API services, and a reduction in API maintenance.
Let’s see how ChatGPT might be used to reinvigorate APIs by creating an OpenAPI specification for an existing API with existing documentation. For our purposes, the API that will be used is “Where the ISS at?” which returns information about the International Space Station. The “Where the ISS at?” documentation can also be found on the Wayback Machine — just in case the main website disappears.
Full file details for ChatGPT questions and responses used in the article can be found in the GitHub Repository - ChatGPT OpenAPI specification.
Using ChatGPT version 3.5, we asked the following:
ChatGTP OpenAPI specification result
The results that ChatGPT produces are non-deterministic, which means the same question submitted at different times, will most probably produce different results. While creating this article, the above question was asked multiple times on ChatGPT which returned different but “similar” results for the questions. Repeating the above question will likely create different results from the ones below.
Due to this, ChatGPT isn’t something that could easily be used within an automated CI/CD pipeline as the results aren’t likely to be the same. This non-deterministic nature also means at times bits of the OpenAPI specification didn’t appear correctly in one result but did in another. Manually comparing the different results and combining them manually might be another approach to creating an initial OpenAPI specification.
Taking the generated OpenAPI specification from ChatGPT, the next step was to validate the results. The OpenAPI ecosystem has many tools that can validate an OpenAPI specification. One of those is Kong Insomnia.
Insomnia includes a default linter that can check to see how well the OpenAPI specification is formatted compared to the specification. The Insomnia lint ruleset can also be custom-defined within Insomnia if a certain style needs to be adhered to.
ChatGPT OpenAPI specification in Kong Insomnia
The ChatGPT-generated OpenAPI specification has 2 errors and 11 warnings. The 2 errors are related to the parameters not being identified correctly, this can be fixed by changing /coordinates/{lat,lon}: to /coordinates/{lat},{lon}:
To tackle the warnings from the previous ChatGPT results, let’s apply a custom naming style for operations and use a specific OpenAPI specification version. The ChatGPT question was rephased to:
ChatGPT’s second OpenAPI specification response in Kong Insomnia
This second ChatGPT-generated OpenAPI specification has 3 errors and 6 warnings. As before, 2 errors are related to the parameters not being identified correctly. This can be fixed by changing /coordinates/{lat,lon}: to /coordinates/{lat},{lon}:
Correctly indenting the contact information removes the other error and contact missing warning.
To fix the global tags missing, the following was added:
The second generated OpenAPI specification successfully linted in Kong Insomnia
An advantage of using an OpenAPI specification is that it can be versioned. In this article, several different OpenAPI specifications have been created which build on top of each other. ChatGPT could be used to create a rough and ready initial specification version that is shared with developers. Then over time, updated specification versions could be released. These different versions can be managed in a developer portal to enable quicker API development, quicker uptake of API services, and a reduction in API maintenance.
Different “Where the ISS at?” versions in the Kong Konnect Developer Portal
ChatGPT can generate an almost complete and working OpenAPI specification, but in both cases, “minor” issues needed to be addressed which were identified using an OpenAPI specification linter. While the fixed version of the OpenAPI specification is syntactically correct, the OpenAPI specification can be further refined for example updating the description fields, adding default values for parameters, validating parameters, etc. so it is more useful for developers.
The above work was based on one API that is well-documented in something other than an OpenAPI specification. Applying ChatGPT to an API with minimal documentation may have completely different results.
ChatGPT is an option to consider when an API has some existing documentation and a quick initial cut of an OpenAPI specification is required with minor changes. Expecting a fully complete generated OpenAPI specification with a repeatable output from ChatGPT using the above approach in 2023 is unrealistic. But in 5 or 10 years, who knows how far things will have progressed?
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?”
Ever feel like you're fighting an uphill battle with your API strategy? You're building APIs faster than ever, but somehow everything feels harder. Wasn’t API-first supposed to make all this easier? Well, you're not alone. And now industry analys
Kong-quer the Agentic AI Hackathon 🚀 Calling all builders, tinkerers, and API innovators. The Kong Hackathon is back for API Summit 2025 ! This year, we’re challenging developers worldwide to create projects that don’t just react, they think , a
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
This is part one of a series exploring how Kong AI Gateway can be used in an AI Agent development with LangGraph. The series comprises three parts: Basic ReAct AI Agent with Kong AI Gateway Single LLM ReAct AI Agent with Kong AI Gateway and LangGr
What Is RAG, and Why Should You Use It? RAG (Retrieval-Augmented Generation) is not a new concept in AI, and unsurprisingly, when talking to companies, everyone seems to have their own interpretation of how to implement it. So, let’s start with a r