Skip to content

docs: Add API specification links to user guides #4348

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
YASHMAHAKAL wants to merge 6 commits into
base: main
Choose a base branch
from
Open

docs: Add API specification links to user guides #4348

YASHMAHAKAL wants to merge 6 commits into from
+20 −21

Conversation

@YASHMAHAKAL
Copy link

@YASHMAHAKAL YASHMAHAKAL commented Dec 13, 2025 •
edited
Loading

docs: Add API specification links to user guides

What type of PR is this?

/kind documentation

What this PR does / why we need it:

This PR adds links to the API specification from user guides, making it easier for users to navigate from guide documentation to the detailed API reference for the types and fields being discussed.

Which issue(s) this PR fixes:

Fixes #4347

Description:

Added API specification links to 10 user guide files, linking relevant API types to their definitions in the generated API reference documentation. Each link points to ../reference/spec.md#gateway.networking.k8s.io/v1.<TypeName> following the established pattern used elsewhere in the documentation.

Files Modified:

  1. site-src/guides/getting-started/simple-gateway.md

    • Added links for: Gateway, GatewayClass, ParentReference, HTTPBackendRef

  2. site-src/guides/grpc-routing.md

    • Added link for: GRPCRoute

  3. site-src/guides/http-cors.md

    • Added link for: HTTPCORSFilter

  4. site-src/guides/http-header-modifier.md

    • Added links for: HTTPHeaderFilter (for both RequestHeaderModifier and ResponseHeaderModifier)

  5. site-src/guides/http-method-matching.md

    • Added link for: HTTPRouteMatch

  6. site-src/guides/http-query-param-matching.md

    • Added link for: HTTPQueryParamMatch

  7. site-src/guides/http-request-mirroring.md

    • Added link for: HTTPRequestMirrorFilter

  8. site-src/guides/http-timeouts.md

    • Added link for: HTTPRouteTimeouts

  9. site-src/guides/tls.md

    • Added links for: Listener, GatewayTLSConfig, BackendTLSPolicy

  10. site-src/guides/traffic-splitting.md

    • Added link for: HTTPBackendRef
Added API specification links to user guide documentation for easier navigation to API reference.

Copilot AI review requested due to automatic review settings December 13, 2025 13:55
@k8s-ci-robot k8s-ci-robot added do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. kind/documentation Categorizes issue or PR as related to documentation. do-not-merge/release-note-label-needed Indicates that a PR should not merge because it's missing one of the release note labels. labels Dec 13, 2025
@k8s-ci-robot k8s-ci-robot requested a review from rikatz December 13, 2025 13:55
@linux-foundation-easycla
Copy link

linux-foundation-easycla bot commented Dec 13, 2025 •
edited
Loading

CLA Signed

The committers listed above are authorized under a signed CLA.

@k8s-ci-robot
Copy link
Contributor

k8s-ci-robot commented Dec 13, 2025

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: YASHMAHAKAL
Once this PR has been reviewed and has the lgtm label, please assign thockin for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot added needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Dec 13, 2025
@k8s-ci-robot
Copy link
Contributor

k8s-ci-robot commented Dec 13, 2025

Welcome @YASHMAHAKAL!

It looks like this is your first PR to kubernetes-sigs/gateway-api 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/gateway-api has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

@k8s-ci-robot
Copy link
Contributor

k8s-ci-robot commented Dec 13, 2025

Hi @YASHMAHAKAL. Thanks for your PR.

I'm waiting for a github.com member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

@k8s-ci-robot k8s-ci-robot added the cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. label Dec 13, 2025
Copilot AI reviewed Dec 13, 2025
View reviewed changes
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR enhances user guide documentation by adding links to the API specification for key Gateway API types. The changes make it easier for users to navigate from conceptual guide documentation to detailed API reference documentation for the types and fields being discussed.

  • Adds API specification links following the established pattern ../reference/spec.md#gateway.networking.k8s.io/v1.<TypeName>
  • Links are added inline within explanatory text where API types are first introduced or discussed
  • All links point to v1 API types, consistent with the current GA status of the referenced types

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated no comments.

Show a summary per file
File Description
site-src/guides/getting-started/simple-gateway.md Added API spec links for core concepts: Gateway, GatewayClass, ParentReference, and HTTPBackendRef
site-src/guides/grpc-routing.md Added API spec link for GRPCRoute type
site-src/guides/http-cors.md Added API spec link for HTTPCORSFilter
site-src/guides/http-header-modifier.md Added API spec links for RequestHeaderModifier and ResponseHeaderModifier (both link to HTTPHeaderFilter)
site-src/guides/http-method-matching.md Added API spec link for HTTPRouteMatch
site-src/guides/http-query-param-matching.md Added API spec link for HTTPQueryParamMatch
site-src/guides/http-request-mirroring.md Added API spec link for HTTPRequestMirrorFilter
site-src/guides/http-timeouts.md Added API spec link for HTTPRouteTimeouts
site-src/guides/tls.md Added API spec links for Listener, GatewayTLSConfig, and BackendTLSPolicy
site-src/guides/traffic-splitting.md Added API spec link for HTTPBackendRef (weights)

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@k8s-ci-robot k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. release-note Denotes a PR that will be considered when it comes time to generate release notes. and removed cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. do-not-merge/release-note-label-needed Indicates that a PR should not merge because it's missing one of the release note labels. labels Dec 13, 2025
@YASHMAHAKAL YASHMAHAKAL force-pushed the add-api-spec-links-to-guides branch from b5f7b53 to c39a406 Compare December 13, 2025 14:23
@YASHMAHAKAL YASHMAHAKAL requested a review from Copilot December 13, 2025 14:25
Copilot AI reviewed Dec 13, 2025
View reviewed changes
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@YASHMAHAKAL YASHMAHAKAL mentioned this pull request Dec 13, 2025
Open
@YASHMAHAKAL
Add API specification links to user guides
6f40c27 
Add links to relevant API specification sections in documentation
guides to improve navigation between practical examples and detailed
API documentation.

This addresses issue 4347 by adding links to the following guides:
- HTTP feature guides (CORS, timeouts, method matching, etc.)
- gRPC and traffic splitting guides
- TLS configuration guide
- Getting started guide

All links follow the established pattern used in existing guides
and reference the correct v1 API types.

Fixes 4347

Signed-off-by:  YASHMAHAKAL <[email protected]>
@YASHMAHAKAL YASHMAHAKAL force-pushed the add-api-spec-links-to-guides branch from c39a406 to 6f40c27 Compare December 13, 2025 16:35
@k8s-ci-robot k8s-ci-robot removed the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label Dec 13, 2025
@rikatz
Copy link
Member

rikatz commented Dec 15, 2025

/ok-to-test

@k8s-ci-robot k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Dec 15, 2025
rikatz
rikatz suggested changes Dec 15, 2025
View reviewed changes
Copy link
Member

@rikatz rikatz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The links are broken :( I've left a comment on how you can check the pre-rendered pages.

site-src/guides/getting-started/simple-gateway.md Outdated

The Gateway represents the instantiation of a logical load balancer and the
GatewayClass defines the load balancer template when users create a Gateway.
The [Gateway](../../reference/spec.md#gateway.networking.k8s.io/v1.Gateway) represents the instantiation of a logical load balancer and the
Copy link
Member

@rikatz rikatz Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The links seem to be generated wrong.

As an example, here it should be something like:

../../reference/spec/#gateway

If you want to take a look how your pages are generated, and check for any broken link, please do at the preview page: https://deploy-preview-4348--kubernetes-sigs-gateway-api.netlify.app/

This page is updated once you update your PR.

Thanks!

@YASHMAHAKAL
Copy link
Author

YASHMAHAKAL commented Dec 15, 2025

greetings @rikatz !! Thank you for your review and suggestions, i'll be making corrections as suggested...Anything else you expect regarding the changes or any advice ??

@YASHMAHAKAL
Copy link
Author

YASHMAHAKAL commented Dec 16, 2025

Greetings @rikatz, As per your suggestions, i've made required appropriate corrections... Would like to know if anything still wrong : )

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@youngnick youngnick Awaiting requested review from youngnick

+1 more reviewer

@rikatz rikatz rikatz requested changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/documentation Categorizes issue or PR as related to documentation. ok-to-test Indicates a non-member PR verified by an org member that is safe to test. release-note Denotes a PR that will be considered when it comes time to generate release notes. size/M Denotes a PR that changes 30-99 lines, ignoring generated files.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Guides should include links to the relevant parts of the API specification

3 participants

@YASHMAHAKAL @k8s-ci-robot @rikatz