[TT-13758] Generate API docs

[titpetric]

TT-13758

Summary	[docs/lint] Gateway specific API documentation
Type	Story
Status	In Code Review
Points	N/A
Labels	SESAP

---

User description

The PR extends the docs taskfile to provide a fmt target (clear formatting rules), and a generate (gen, codegen) target, that generates two new docs from godocs package information:

• Internal API documentation for everything under /internal
• Plugin focused API subset (/ctx, /storage, /user, and /log)

Preview for internal.md

Preview for plugin-apis.md

https://tyktech.atlassian.net/browse/TT-13758

[buger]

A JIRA Issue ID is missing from your branch name, PR title and PR description! 🦄

Your branch: docs/generate-api-docs

Your PR title: [development] Generate API docs

Your PR description: The PR extends the docs taskfile to provide a `fmt` target (clear formatting rules), and a `generate` (gen, codegen) target, that generates two new docs from godocs package information:

• Internal API documentation for everything under /internal
• Plugin focused API subset (/ctx, /storage, /user, and /log)

If this is your first time contributing to this repository - welcome!

---

Please refer to jira-lint to get started.

Without the JIRA Issue ID in your branch name you would lose out on automatic updates to JIRA via SCM; some GitHub status checks might fail.

Valid sample branch names:

‣ feature/shiny-new-feature--mojo-10'
‣ 'chore/changelogUpdate_mojo-123'
‣ 'bugfix/fix-some-strange-bug_GAL-2345'

[github-actions]

API Changes

no api changes detected

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Possible Issue The start method in the Test struct initializes and starts a gateway but lacks error handling for critical operations like gw.startServer() and gw.setupGlobals(). This could lead to silent failures. // init and create gw ctx, cancel := context.WithCancel(context.Background()) log.Info("starting test") s.ctx = ctx s.cancel = func() { cancel() log.Info("Cancelling test context") } gw := s.newGateway(genConf) gw.setupPortsWhitelist() gw.startServer() gw.setupGlobals() // Set up a default org manager so we can traverse non-live paths if !gw.GetConfig().SupressDefaultOrgStore { gw.DefaultOrgStore.Init(gw.getGlobalStorageHandler("orgkey.", false)) gw.DefaultQuotaStore.Init(gw.getGlobalStorageHandler("orgkey.", false)) } s.GlobalConfig = gw.GetConfig() scheme := "http://" if s.GlobalConfig.HttpServerOptions.UseSSL { scheme = "https://" } s.URL = scheme + gw.DefaultProxyMux.getProxy(gw.GetConfig().ListenPort, gw.GetConfig()).listener.Addr().String() s.testRunner = &test.HTTPTestRunner{ RequestBuilder: func(tc *test.TestCase) (*http.Request, error) { tc.BaseURL = s.URL if tc.ControlRequest { if s.config.SeparateControlAPI { tc.BaseURL = scheme + s.controlProxy().listener.Addr().String() } else if s.GlobalConfig.ControlAPIHostname != "" { tc.Domain = s.GlobalConfig.ControlAPIHostname } } r, err := test.NewRequest(tc) if tc.AdminAuth { r = s.withAuth(r) } if s.config.Delay > 0 { tc.Delay = s.config.Delay } return r, err }, Do: test.HttpServerRunner(), } return gw Documentation Generation The generate:plugin task appends plugin API documentation to plugin-apis.md without clearing or validating the file beforehand. This could lead to duplicate or inconsistent documentation. generate:plugin: internal: true desc: "Generate plugin API godocs." cmds: - cd '{{.root}}/ctx' && go-fsck docs ./... > ../docs/dev/plugin-apis.md && cd .. - cd '{{.root}}/user' && go-fsck docs ./... >> ../docs/dev/plugin-apis.md && cd .. - cd '{{.root}}/storage' && go-fsck docs ./... >> ../docs/dev/plugin-apis.md && cd .. - cd '{{.root}}/log' && go-fsck docs ./... >> ../docs/dev/plugin-apis.md && cd ..

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Add error handling for critical methods Ensure that the start method properly handles errors from gw.startServer() and gw.setupGlobals() to avoid potential runtime issues if these operations fail. gateway/test.go [90-91] -gw.startServer() -gw.setupGlobals() +if err := gw.startServer(); err != nil { + log.WithError(err).Error("Failed to start server") + return nil +} +if err := gw.setupGlobals(); err != nil { + log.WithError(err).Error("Failed to setup globals") + return nil +} Suggestion importance[1-10]: 9 __ Why: Adding error handling for gw.startServer() and gw.setupGlobals() is crucial as these are critical operations. Without proper error handling, failures in these methods could lead to runtime issues or undefined behavior.	High
	Check for nil before shutdown Validate that s.HttpHandler is not nil before calling Shutdown to prevent potential nil pointer dereference. gateway/test.go [163-165] -err := s.HttpHandler.Shutdown(ctxShutDown) +if s.HttpHandler != nil { + err := s.HttpHandler.Shutdown(ctxShutDown) + if err != nil { + log.WithError(err).Error("shutting down the http handler") + } else { + log.Info("server exited properly") + } +} Suggestion importance[1-10]: 8 __ Why: Validating that s.HttpHandler is not nil before calling Shutdown prevents potential nil pointer dereference, which is a common source of runtime errors in Go.	Medium
General	Handle errors during NewRelic shutdown Ensure s.Gw.NewRelicApplication.Shutdown handles errors gracefully to avoid silent failures during shutdown. gateway/test.go [173] -s.Gw.NewRelicApplication.Shutdown(5 * time.Second) +if err := s.Gw.NewRelicApplication.Shutdown(5 * time.Second); err != nil { + log.WithError(err).Error("Failed to shutdown NewRelic application") +} Suggestion importance[1-10]: 7 __ Why: Handling errors during s.Gw.NewRelicApplication.Shutdown ensures that any issues during the shutdown process are logged and not silently ignored, improving reliability and debuggability.	Medium
	Validate mdox installation before use Add a validation step to ensure that the mdox tool is installed before running formatting commands to prevent task failures. docs/Taskfile.yml [36] -- cd '{{.root}}/docs' && mdox fmt --no-soft-wraps $(find -name '*.md') && cd .. +- if ! command -v mdox &> /dev/null; then echo "mdox not installed"; exit 1; fi + cd '{{.root}}/docs' && mdox fmt --no-soft-wraps $(find -name '*.md') && cd .. Suggestion importance[1-10]: 6 __ Why: Adding a validation step for the mdox tool ensures that the formatting task does not fail unexpectedly due to the tool being unavailable, improving robustness and user experience.	Low

[buger]

This PR is too huge for one to review 💔

Additions	5917 🙅‍♀️
Expected	⬇️ 800

Consider breaking it down into multiple small PRs.

Check out this guide to learn more about PR best-practices.

[buger]

Let's make that PR title a 💯 shall we? 💪

Your PR title and story title look slightly different. Just checking in to know if it was intentional!

Story Title	[docs/lint] Gateway specific API documentation
PR Title	[TT-13758] Generate API docs

Check out this guide to learn more about PR best-practices.

[titpetric]

Pausing the merge on this, noticed a documentation issue when covering OAS docs that requires a docgen update loop.

[sonarqubecloud]

Quality Gate failed

Failed conditions
11 Security Hotspots
E Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[buger]

💔 The detected issue is not in one of the allowed statuses 💔

Detected Status	Closed	❌
Allowed Statuses	In Dev,In Code Review,Ready for Testing,In Test,In Progress,In Review	✔️

Please ensure your jira story is in one of the allowed statuses

[buger]

💔 The detected issue is not in one of the allowed statuses 💔

Detected Status	Closed	❌
Allowed Statuses	In Dev,In Code Review,Ready for Testing,In Test,In Progress,In Review	✔️

Please ensure your jira story is in one of the allowed statuses