doc: add gateway API features in KIC 2.4

[randmonkey]

Summary

Add introduction of gateway API features of KIC for version 2.4 and later.

Reason

fixes #4026.

Testing

[netlify]

✅ Deploy Preview for kongdocs ready!

Name	Link
🔨 Latest commit	1d3e33e
🔍 Latest deploy log	https://app.netlify.com/sites/kongdocs/deploys/62fd40b2ae5b6300099f22bb
😎 Deploy Preview	https://deploy-preview-4231--kongdocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[pmalek]

I wonder if that will work together with #4230 🤔

[randmonkey]

Wanted to make some discussions on introducing supported gateway API features:

• Where and what to put on docs site?
  • put currently supported gateway API resources and features on a section near top in guides/using-gateway-api, like this PR.
    • pros: could see all the features we support at the first glance
    • concerns: (1) the section may be too long as we implement new features; (2) contents somewhat are duplicating with Alpha limitations section.
  • put currently supported gateway API resources, and add a link to a page in reference part introducing supported features of each resource.
    • pros: shorten the section; also can see what we support in a brief
    • concerns: need an extra page to introduce supported features of Gateway and *Routes, not direct
  • put it together with Alpha limitations section, change this section to introduce "What we support and what we do not support currently"
• Another question: how to introduce features cross versions? In different versions, the status of support may change, so we need to add/update/delete items through versions.
  • use if version around items? might make the section(and Alpha limitation) looks in a mess in source.
  • copy contents and change the diffs for each version? might make the section become too long.

[randmonkey]

I wonder if that will work together with #4230 thinking

maybe push my changes to the branch in #4230 and review them together?

[pmalek]

Wanted to make some discussions on introducing supported gateway API features:

• Where and what to put on docs site?

  • put currently supported gateway API resources and features on a section near top in guides/using-gateway-api, like this PR.

    • pros: could see all the features we support at the first glance
    • concerns: (1) the section may be too long as we implement new features; (2) contents somewhat are duplicating with Alpha limitations section.

  • put currently supported gateway API resources, and add a link to a page in reference part introducing supported features of each resource.

    • pros: shorten the section; also can see what we support in a brief
    • concerns: need an extra page to introduce supported features of Gateway and *Routes, not direct

  • put it together with Alpha limitations section, change this section to introduce "What we support and what we do not support currently"

• Another question: how to introduce features cross versions? In different versions, the status of support may change, so we need to add/update/delete items through versions.

  • use if version around items? might make the section(and Alpha limitation) looks in a mess in source.
  • copy contents and change the diffs for each version? might make the section become too long.

To me this should be somewhere near the top of a docs page. Haven't made my mind yet about which one (of using-gateway-api.md or introduced in #4230 gateway-api.md) so to me either is fine but the change will need to account for what's already covering this subject and ideally merge it into one section of "what's supported and what are the limitations of particular version".

As of source code for docs being messy: oh well, it's not going to be the end of the world. We'll just add/remove particular features/limitations to/from particular versions' lists.

[pmalek]

LGTM. I'll +1 this but let's discuss this with @rainest and put this together with his #4230

[rainest]

put currently supported gateway API resources, and add a link to a page in reference part introducing supported features of each resource.

I like this option. There's not much reason the existing limitations section went into the guide other than that the guide was the only article. A reference page sounds like a good home for a by-type list of things we do or do not support.

For the most part, our reference should omit core features that we support: any core feature not otherwise mentioned is assumed supported. We'd list only:

• Extended features that we do support.
• Core features that we do not support.

So roughly, the page would be a section for each type with Extended feature support and Limitations sections, with the existing Limitations section in the guide removed and broken into the the individual type subsections.

The if template syntax can get a bit messy, but it's what we've got.

Since that reference is a new page, we wouldn't need to worry about conflicts with #4230

[pmalek]

I believe that in order to fix (or rather ignore) these spelling errors, you can add exceptions to https://github.com/Kong/docs.konghq.com/blob/main/.github/styles/kong/dictionary.txt