Few things are more frustrating than encountering a product with either no documentation or worse: documentation that leads you astray. When it comes to developing APIs, schemas typically define how requests and responses are formatted and guide how clients and services exchange data. Commonly, schemas aren't used to generate documentation or software development kits (SDKs), allowing them to become stale and inaccurate.
At Kong, we're committed to a different approach — having a single source of truth for our schemas. These schemas power both our code and our documentation, guaranteeing its accuracy and timeliness.
As a step forward, we're excited to announce the availability of our beta OpenAPI specifications for both the Kong Gateway Admin API and Konnect Runtime Groups configuration API. These specifications are designed to provide everything you need, all presented in a standardized format you’re already familiar with. The best part? They effortlessly integrate with your existing toolchain.
What does this mean for you?
In an ideal world, all of our APIs would follow a design-first approach where the OpenAPI specification is the source of truth. Whilst this is true for our new Konnect APIs, Kong Gateway is a long-running open source project that treats Lua schemas as its source of truth.
Lua schemas being the source of truth with handwritten markdown documentation meant that API documentation lagged behind code changes, leading to confusion and frustration both internally and externally. To address this, we decided to make the Kong Gateway code the single source of truth for our API documentation and generate JSON schema entities from the code. Every endpoint, parameter, and response is now derived from and defined in the Kong Gateway code. This is to ensure that our API remains accurate and up to date.
Using the code as the source of truth didn't mean that we got everything for free. API documentation that's missing descriptions about what each field in the API is used for is almost useless. This led us to upgrade the underlying Lua schemas to contain description fields for every entity and create a generator that extracts all of the parameters, constraints, and descriptions when generating an Open API spec.
While our specs are robust and reliable enough that we're using them internally, we're still actively working on the generation process. But we wanted to give everyone access to these tools to empower them in the Kong ecosystem. Hopefully, this encourages you to explore, test, and provide any feedback related to these specs so that we can improve them to the point that they meet the same standard as the rest of our products.
Our long-term vision is to move to a design-first approach and treat OpenAPI as the source of truth for Kong Gateway. However, there are a lot of benefits from having a spec (even one generated from code) and we don't want perfect to be the enemy of better.You can find the specs hosted on our Docs site, and if you want to get started in Kong Insomnia, you can use these dedicated Kong Insomnia links for Kong Gateway and Kong Konnect.
If you spot any bugs, please let us know by emailing team-docs@konghq.com. And if you build anything cool with the specs, come tell us in the Kong Community Slack.
Imagine this: You're documenting an unreleased feature, and your documentation requires screenshots. However, you're working in an internal environment that includes features you don't want to reveal to the public. What do you do? We faced this exac
Kong will crash on the ARM64 platform (the machine with Mac M1/M2 chips or any ARM64 platform). The error message shows the crash is triggered by the SIGILL signal, which means there is an illegal instruction in the Kong binary code. And it turns out
Creating API design guidelines is a common practice for many enterprises. The goal? Ensuring that all teams involved in API development will adhere to them. However, this goal is often not achieved, as developers may not take the time to read, study
Kong Konnect is a powerful SaaS-based API lifecycle management platform that provides a fast path for people looking to get started with Kong API Gateway. For existing users of Kong’s open-source gateway, it offers a way to rapidly take advantage of
Kong’s open-source API Gateway is a highly successful project with over 33k stars on GitHub and 293 contributors. Kong provides a powerful platform that can be extended using hundreds of plugins provided by Kong, ecosystem partners, and the community