github-starred/pangolin
2
0
Fork 0
mirror of https://github.com/fosrl/pangolin.git synced 2026-07-17 07:04:36 -05:00
Code Issues 1.6k Packages Projects Releases 79 Wiki Activity

[PR #3102] [MERGED] Improve OpenAPI response payload typing for Swagger data schemas #37982

New Issue
Closed
opened 2026-06-20 16:25:58 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-06-20 16:25:58 -05:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/fosrl/pangolin/pull/3102
Author: @Copilot
Created: 5/17/2026
Status: ✅ Merged
Merged: 5/31/2026
Merged by: @oschwartz10612

Base: main ← Head: copilot/fix-documentation-input-output-types

📝 Commits (5)

  • 9cec711 Fix custom parser OpenAPI types and add structured default response schema
  • a0a093e Document all registerPath responses and normalize OpenAPI parser schemas
  • 15a9eb2 Add concrete OpenAPI data schemas for selected routes
  • f3bee70 Reformat generated OpenAPI response schemas for readability
  • 81ed391 Remove obsolete stoi import from blueprint OpenAPI route

📊 Changes

183 files changed (+2875 additions, -245 deletions)

View changed files

📝 server/integrationApiServer.ts (+9 -3)
📝 server/lib/ip.ts (+7 -1)
➕ server/lib/openapi/createApiResponseSchema.ts (+11 -0)
📝 server/private/routers/alertRule/createAlertRule.ts (+16 -1)
📝 server/private/routers/alertRule/deleteAlertRule.ts (+16 -1)
📝 server/private/routers/alertRule/getAlertRule.ts (+16 -1)
📝 server/private/routers/alertRule/listAlertRules.ts (+16 -1)
📝 server/private/routers/alertRule/updateAlertRule.ts (+15 -1)
📝 server/private/routers/approvals/processPendingApproval.ts (+1 -1)
📝 server/private/routers/auditLogs/exportAccessAuditLog.ts (+17 -1)
📝 server/private/routers/auditLogs/exportActionAuditLog.ts (+17 -1)
📝 server/private/routers/auditLogs/exportConnectionAuditLog.ts (+17 -1)
📝 server/private/routers/auditLogs/queryAccessAuditLog.ts (+16 -1)
📝 server/private/routers/auditLogs/queryActionAuditLog.ts (+16 -1)
📝 server/private/routers/auditLogs/queryConnectionAuditLog.ts (+16 -1)
📝 server/private/routers/billing/getOrgUsage.ts (+16 -1)
📝 server/private/routers/certificates/getCertificate.ts (+16 -1)
📝 server/private/routers/certificates/restartCertificate.ts (+18 -3)
📝 server/private/routers/domain/checkDomainNamespaceAvailability.ts (+16 -1)
📝 server/private/routers/domain/listDomainNamespaces.ts (+27 -1)

...and 80 more files

📄 Description

Swagger response docs were still advertising data as unknown | null, which hid the actual payload shape for many endpoints. This change starts replacing those generic envelopes with route-specific response schemas so successful responses are inspectable in the docs.

  • Response envelope helper

    • Added createApiResponseSchema(...) to standardize the outer API envelope while allowing each route to provide a concrete data schema.
    • Keeps the shared response contract (data, success, error, message, status) without repeating the wrapper logic in every route.

  • Concrete data schemas for high-confidence routes

    • Replaced generic z.unknown().nullable() with route-specific payload schemas for a first set of routes where the response shape was already explicit or easy to derive.
    • Covered a mix of:
      • single-object responses
      • create/update responses returning IDs or small payloads
      • list endpoints with pagination
    • Includes routes in:
      • org
      • domain
      • API keys
      • IDP / org IDP
      • event streaming destinations
      • health checks
      • alert rules
      • selected user/client/site helper endpoints

  • Swagger usability improvements

    • List endpoints now show the actual collection item shape and pagination block.
    • Small create/update routes now document the returned identifiers instead of opaque unknown.
    • This makes the docs materially more useful without changing runtime response behavior.

  • Cleanup

    • Repaired a handful of commented registerPath(...) blocks that were malformed by the earlier bulk response replacement.
    • Removed one stale stoi import left behind after parser normalization.
// before
responses: {
  200: {
    content: {
      "application/json": {
        schema: z.object({
          data: z.unknown().nullable(),
          success: z.boolean(),
          error: z.boolean(),
          message: z.string(),
          status: z.number()
        })
      }
    }
  }
}

// after
const ListDomainsResponseDataSchema = z.object({
  domains: z.array(
    z.object({
      domainId: z.string(),
      baseDomain: z.string(),
      verified: z.boolean(),
      type: z.string().nullable()
    })
  ),
  pagination: z.object({
    total: z.number(),
    limit: z.number(),
    offset: z.number()
  })
});

responses: {
  200: {
    content: {
      "application/json": {
        schema: createApiResponseSchema(ListDomainsResponseDataSchema)
      }
    }
  }
}

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/fosrl/pangolin/pull/3102 **Author:** [@Copilot](https://github.com/apps/copilot-swe-agent) **Created:** 5/17/2026 **Status:** ✅ Merged **Merged:** 5/31/2026 **Merged by:** [@oschwartz10612](https://github.com/oschwartz10612) **Base:** `main` ← **Head:** `copilot/fix-documentation-input-output-types` --- ### 📝 Commits (5) - [`9cec711`](https://github.com/fosrl/pangolin/commit/9cec711427d1fdf953bee668eb04e6f7dfe48a82) Fix custom parser OpenAPI types and add structured default response schema - [`a0a093e`](https://github.com/fosrl/pangolin/commit/a0a093ed0b0b571ec26ff3dc923cbb982291bf64) Document all registerPath responses and normalize OpenAPI parser schemas - [`15a9eb2`](https://github.com/fosrl/pangolin/commit/15a9eb28d9d1ac51e7dd7e2567a5c43c82d8404a) Add concrete OpenAPI data schemas for selected routes - [`f3bee70`](https://github.com/fosrl/pangolin/commit/f3bee70c23824f2e572a7018b13e740499935825) Reformat generated OpenAPI response schemas for readability - [`81ed391`](https://github.com/fosrl/pangolin/commit/81ed391efb87ac3084d0953ee6687dbc05e0b9fb) Remove obsolete stoi import from blueprint OpenAPI route ### 📊 Changes **183 files changed** (+2875 additions, -245 deletions) <details> <summary>View changed files</summary> 📝 `server/integrationApiServer.ts` (+9 -3) 📝 `server/lib/ip.ts` (+7 -1) ➕ `server/lib/openapi/createApiResponseSchema.ts` (+11 -0) 📝 `server/private/routers/alertRule/createAlertRule.ts` (+16 -1) 📝 `server/private/routers/alertRule/deleteAlertRule.ts` (+16 -1) 📝 `server/private/routers/alertRule/getAlertRule.ts` (+16 -1) 📝 `server/private/routers/alertRule/listAlertRules.ts` (+16 -1) 📝 `server/private/routers/alertRule/updateAlertRule.ts` (+15 -1) 📝 `server/private/routers/approvals/processPendingApproval.ts` (+1 -1) 📝 `server/private/routers/auditLogs/exportAccessAuditLog.ts` (+17 -1) 📝 `server/private/routers/auditLogs/exportActionAuditLog.ts` (+17 -1) 📝 `server/private/routers/auditLogs/exportConnectionAuditLog.ts` (+17 -1) 📝 `server/private/routers/auditLogs/queryAccessAuditLog.ts` (+16 -1) 📝 `server/private/routers/auditLogs/queryActionAuditLog.ts` (+16 -1) 📝 `server/private/routers/auditLogs/queryConnectionAuditLog.ts` (+16 -1) 📝 `server/private/routers/billing/getOrgUsage.ts` (+16 -1) 📝 `server/private/routers/certificates/getCertificate.ts` (+16 -1) 📝 `server/private/routers/certificates/restartCertificate.ts` (+18 -3) 📝 `server/private/routers/domain/checkDomainNamespaceAvailability.ts` (+16 -1) 📝 `server/private/routers/domain/listDomainNamespaces.ts` (+27 -1) _...and 80 more files_ </details> ### 📄 Description Swagger response docs were still advertising `data` as `unknown | null`, which hid the actual payload shape for many endpoints. This change starts replacing those generic envelopes with route-specific response schemas so successful responses are inspectable in the docs. - **Response envelope helper** - Added `createApiResponseSchema(...)` to standardize the outer API envelope while allowing each route to provide a concrete `data` schema. - Keeps the shared response contract (`data`, `success`, `error`, `message`, `status`) without repeating the wrapper logic in every route. - **Concrete `data` schemas for high-confidence routes** - Replaced generic `z.unknown().nullable()` with route-specific payload schemas for a first set of routes where the response shape was already explicit or easy to derive. - Covered a mix of: - single-object responses - create/update responses returning IDs or small payloads - list endpoints with pagination - Includes routes in: - org - domain - API keys - IDP / org IDP - event streaming destinations - health checks - alert rules - selected user/client/site helper endpoints - **Swagger usability improvements** - List endpoints now show the actual collection item shape and pagination block. - Small create/update routes now document the returned identifiers instead of opaque `unknown`. - This makes the docs materially more useful without changing runtime response behavior. - **Cleanup** - Repaired a handful of commented `registerPath(...)` blocks that were malformed by the earlier bulk response replacement. - Removed one stale `stoi` import left behind after parser normalization. ```ts // before responses: { 200: { content: { "application/json": { schema: z.object({ data: z.unknown().nullable(), success: z.boolean(), error: z.boolean(), message: z.string(), status: z.number() }) } } } } // after const ListDomainsResponseDataSchema = z.object({ domains: z.array( z.object({ domainId: z.string(), baseDomain: z.string(), verified: z.boolean(), type: z.string().nullable() }) ), pagination: z.object({ total: z.number(), limit: z.number(), offset: z.number() }) }); responses: { 200: { content: { "application/json": { schema: createApiResponseSchema(ListDomainsResponseDataSchema) } } } } ``` --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
GiteaMirror added the pull-request label 2026-06-20 16:25:58 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
api
authentication
bug
config
dependencies
docker
documentation
enhancement
good first issue
help wanted
Improvement
Look Into
needs investigating
networking
new feature
non-critical bug
potential bug
pull-request
Mirrored from GitHub Pull Request
 question
reverse proxy
Security
stale
ui
wontfix
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/pangolin#37982
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?