31013736042

Committed 05 Aug 2026 02:09PM UTC coverage: 80.551% (+0.03%) from 80.524%

Build # 31013736042

Build Type

Pull #1215

github

Committed by

web-flow

Commit Message

Merge 7ad3fa538 into 5835f7701

Pull Request Pull Request #1215: fix: improve generated OpenAPI spec quality for SDK generation

Coverage Stats

5686 of 7580 branches covered (75.01%)

Branch coverage included in aggregate %.

92 of 94 new or added lines in 8 files covered. (97.87%)

17 existing lines in 1 file now uncovered.

10702 of 12765 relevant lines covered (83.84%)

439.67 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

94.78

/src/http/routes/openapi-transform.ts

import { SwaggerTransformObject } from '@fastify/swagger'
import { FastifySchema, RouteOptions } from 'fastify'
import { ROUTE_OPERATIONS } from './operations'

/**
 * @fastify/swagger names every de-duplicated component schema `def-0`, `def-1`, ... by
 * default, even for schemas registered with a meaningful `$id` (bucketSchema, errorSchema).
 * Use the `$id` as the component name instead, falling back to the default `def-N` for
 * anonymous schemas so unrelated inline schemas don't collide.
 */
export function nameSchemaByDollarId(
  json: { $id?: string },
  _baseUri: unknown,
  _fragment: unknown,
  i: number
) {
  return json.$id || `def-${i}`
}

const WILDCARD_PARAM = '*'
const WILDCARD_DOC_NAME = 'wildcard'

/**
 * Fastify's catch-all route segment is `*`, and its request params are keyed by the
 * literal `*` character (`request.params['*']`). @fastify/swagger mirrors that straight
 * into the OpenAPI doc as a path template `{*}` with a parameter named `*`, which isn't a
 * legal parameter/identifier name for any code generator. Rewrite it to a readable name for
 * docs only - the raw url string returned here still goes through Fastify's own `:name`
 * path-param formatting, and `route.schema` (the live validation schema) is never mutated.
 */
function renameWildcardParam(
  schema: FastifySchema,
  url: string
): { schema: FastifySchema; url: string } {
  if (!url.split('/').includes(WILDCARD_PARAM)) {
    return { schema, url }
  }

  const renamedUrl = url
    .split('/')
    .map((segment) => (segment === WILDCARD_PARAM ? `:${WILDCARD_DOC_NAME}` : segment))
    .join('/')

  const params = schema.params as
    | { properties?: Record<string, unknown>; required?: string[] }
    | undefined
  if (!params?.properties?.[WILDCARD_PARAM]) {
    return { schema, url: renamedUrl }
  }

  const { [WILDCARD_PARAM]: wildcardProperty, ...otherProperties } = params.properties
  const renamedParams = {
    ...params,
    properties: { ...otherProperties, [WILDCARD_DOC_NAME]: wildcardProperty },
    required: params.required?.map((name) => (name === WILDCARD_PARAM ? WILDCARD_DOC_NAME : name)),
  }

  return { schema: { ...schema, params: renamedParams }, url: renamedUrl }
}

/**
 * The S3-compatible surface dispatches ~18 real commands (PutObject, ListObjects,
 * CreateMultipartUpload, ...) from a handful of generic Fastify routes based on query
 * string/header matching done entirely inside the internal `s3/router.ts` Router - see
 * `s3/index.ts`. Fastify (and therefore @fastify/swagger) only ever sees the outer
 * catch-all route with no request/response schema, since OpenAPI has no way to express
 * "N distinct operations, same path and method, picked by a query parameter". Documenting
 * that catch-all as-is would give SDK generators a single method with an untyped body and
 * an untyped response for a request that's actually the whole S3 API - worse than nothing.
 * Hide it instead; the real per-command schemas remain the source of truth in s3/commands/*.
 */
function isS3ProtocolCatchAll(schema: FastifySchema | undefined, route: RouteOptions): boolean {
  const operation = (route.config as { operation?: string } | undefined)?.operation
  return (schema?.tags?.includes('s3') ?? false) && !operation
}

/**
 * Derives a stable, unique operationId from the route's `config.operation`
 * (see ROUTE_OPERATIONS in ./operations.ts), e.g. `storage.object.get_public` -> `objectGetPublic`.
 * Routes without a `config.operation` (protocol-level catch-alls like /s3 and /upload/resumable)
 * are left without an operationId.
 */
function operationToId(operation: string): string {
  const parts = operation.split('.').filter((part) => part !== 'storage')
  return parts
    .map((part) =>
      part
        .split('_')
        .filter(Boolean)
        .map((word, i) => (i === 0 ? word : word[0].toUpperCase() + word.slice(1)))
        .join('')
    )
    .map((part, i) => (i === 0 ? part : part[0].toUpperCase() + part.slice(1)))
    .join('')
}

/**
 * Every route can end up hitting setErrorHandler and getting back a {statusCode, error,
 * message, code} body (or, for a subtree with its own formatter, whatever that subtree
 * documents instead) - default the doc to that shape for any otherwise-undocumented 4xx.
 * Doc-only on purpose: several handlers reply with an ad-hoc, partial error body directly
 * (`reply.status(400).send({message: '...'})`, bypassing the formatter entirely), and an
 * earlier version of this defaulted via a real onRoute hook that made Fastify enforce
 * errorSchema's `required` fields during response *serialization* - which threw on exactly
 * those ad-hoc replies (fast-json-stringify errors on a missing required property rather
 * than dropping it). A transform can't affect request handling, so it can't cause that.
 */
function defaultErrorResponse(schema: FastifySchema | undefined): FastifySchema {
  const response = schema?.response as Record<string, unknown> | undefined
  if (schema && response && Object.keys(response).some((status) => /^4xx$/i.test(status))) {
    return schema
  }

  return {
    ...schema,
    response: {
      ...(response ? undefined : { 200: { description: 'Default Response' } }),
      '4xx': { description: 'Error response', $ref: 'errorSchema#' },
      ...response,
    },
  }
}

const MULTIPART_UPLOAD_OPERATIONS = new Set<string>([
  ROUTE_OPERATIONS.CREATE_OBJECT,
  ROUTE_OPERATIONS.UPDATE_OBJECT,
  ROUTE_OPERATIONS.UPLOAD_SIGN_OBJECT,
])

/**
 * createObject/updateObject/uploadSignedObject never set `schema.body` - they read the raw
 * multipart stream directly via `uploadFromRequest` -> `fileUploadFromRequest`
 * (see src/storage/object.ts), without registering `@fastify/multipart`'s
 * `attachFieldsToBody`. That means `request.body` is always `undefined` on these routes, so a
 * real `schema.body` would make Fastify validate that `undefined` (substituted as `null`)
 * against a required-fields schema on every real upload and fail it with a 400 - a production
 * regression, not a docs improvement. Document the multipart shape here instead, transform-only,
 * where - like `defaultErrorResponse` above - it can never reach live request validation.
 */
function documentMultipartUploadBody(schema: FastifySchema, route: RouteOptions): FastifySchema {
  const operation = (route.config as { operation?: string } | undefined)?.operation
  if (!operation || !MULTIPART_UPLOAD_OPERATIONS.has(operation)) {
    return schema
  }

  return {
    ...schema,
    consumes: ['multipart/form-data'],
    body: {
      type: 'object',
      properties: {
        cacheControl: { type: 'string' },
        metadata: { type: 'string' },
        file: { type: 'string', contentEncoding: 'binary' },
      },
      required: ['cacheControl', 'file'],
    },
  }
}

/**
 * OpenAPI requires operationId to be unique across the whole document. `exposeHeadRoutes`
 * auto-derives a HEAD operation from every GET route re-using the same `config.operation`,
 * so the id needs a per-method suffix to stay unique when that happens.
 * Returns a fresh transform bound to its own dedup state, so main/admin specs don't
 * leak collisions into each other when generated in the same process (see export-docs.ts).
 */
export function createOpenApiTransform() {
  const seenIds = new Set<string>()

  return function transformOpenApiSchema({
    schema,
    url,
    route,
  }: {
    schema: FastifySchema
    url: string
    route: RouteOptions
  }): { schema: FastifySchema; url: string } {
    if (isS3ProtocolCatchAll(schema, route)) {
      return { schema: { ...schema, hide: true }, url }
    }

    ;({ schema, url } = renameWildcardParam(schema, url))
    schema = defaultErrorResponse(schema)
    schema = documentMultipartUploadBody(schema, route)

    const operation = (route.config as { operation?: string } | undefined)?.operation

    if (!operation || (schema as { operationId?: string }).operationId) {
      return { schema, url }
    }

    const baseId = operationToId(operation)
    let operationId = baseId
    if (seenIds.has(operationId)) {
      const method = Array.isArray(route.method) ? route.method[0] : route.method
      operationId = baseId + method[0].toUpperCase() + method.slice(1).toLowerCase()
    }
    for (let suffix = 2; seenIds.has(operationId); suffix++) {
      operationId = baseId + suffix
    }
    seenIds.add(operationId)

    return {
      schema: { ...schema, operationId },
      url,
    }
  }
}

/**
 * A handful of paths are reachable both with and without a trailing slash - either because
 * Fastify's own `exposeHeadRoutes` derives a HEAD route from the un-prefixed path (e.g.
 * /health vs /health/) or because a route is explicitly registered both ways (the S3
 * protocol surface). Both forms genuinely work at runtime, but documenting them as two
 * unrelated paths just doubles the number of operations a generated SDK has to deal with
 * for the same endpoint. Keep the slash-less form and fold the other one's methods into it.
 */
export const dedupeTrailingSlashPaths: SwaggerTransformObject = (documentObject) => {
  if (!('openapiObject' in documentObject)) {
    return documentObject.swaggerObject
  }

  const { openapiObject } = documentObject
  const paths = openapiObject.paths as Record<string, Record<string, unknown>> | undefined
  if (!paths) {
    return openapiObject
  }

  for (const url of Object.keys(paths)) {
    if (url === '/' || !url.endsWith('/')) {
      continue
    }

    const canonicalUrl = url.slice(0, -1)
    const canonicalPathItem = paths[canonicalUrl]
    if (!canonicalPathItem) {
      continue
    }

    for (const [method, operation] of Object.entries(paths[url])) {
      canonicalPathItem[method] ??= operation
    }
    delete paths[url]
  }

  return openapiObject
}

1	import { SwaggerTransformObject } from '@fastify/swagger'
2	import { FastifySchema, RouteOptions } from 'fastify'
3	import { ROUTE_OPERATIONS } from './operations'
4
5	/**
6	* @fastify/swagger names every de-duplicated component schema `def-0`, `def-1`, ... by
7	* default, even for schemas registered with a meaningful `$id` (bucketSchema, errorSchema).
8	* Use the `$id` as the component name instead, falling back to the default `def-N` for
9	* anonymous schemas so unrelated inline schemas don't collide.
10	*/
11	export function nameSchemaByDollarId(
12	json: { $id?: string },
13	_baseUri: unknown,
14	_fragment: unknown,
15	i: number
16	) {
17	return json.$id \|\| `def-${i}`	8!
18	}
19
20	const WILDCARD_PARAM = '*'	38✔
21	const WILDCARD_DOC_NAME = 'wildcard'	38✔
22
23	/**
24	* Fastify's catch-all route segment is `*`, and its request params are keyed by the
25	* literal `` character (`request.params['']`). @fastify/swagger mirrors that straight
26	* into the OpenAPI doc as a path template `{}` with a parameter named ``, which isn't a
27	* legal parameter/identifier name for any code generator. Rewrite it to a readable name for
28	* docs only - the raw url string returned here still goes through Fastify's own `:name`
29	* path-param formatting, and `route.schema` (the live validation schema) is never mutated.
30	*/
31	function renameWildcardParam(
32	schema: FastifySchema,
33	url: string
34	): { schema: FastifySchema; url: string } {
35	if (!url.split('/').includes(WILDCARD_PARAM)) {	145✔
36	return { schema, url }	102✔
37	}
38
39	const renamedUrl = url	43✔
40	.split('/')
41	.map((segment) => (segment === WILDCARD_PARAM ? `:${WILDCARD_DOC_NAME}` : segment))	209✔
42	.join('/')
43
44	const params = schema.params as	43✔
45	\| { properties?: Record<string, unknown>; required?: string[] }
46	\| undefined
47	if (!params?.properties?.[WILDCARD_PARAM]) {	43✔
48	return { schema, url: renamedUrl }	17✔
49	}
50
51	const { [WILDCARD_PARAM]: wildcardProperty, ...otherProperties } = params.properties	26✔
52	const renamedParams = {	26✔
53	...params,
54	properties: { ...otherProperties, [WILDCARD_DOC_NAME]: wildcardProperty },
55	required: params.required?.map((name) => (name === WILDCARD_PARAM ? WILDCARD_DOC_NAME : name)),	52✔
56	}
57
58	return { schema: { ...schema, params: renamedParams }, url: renamedUrl }	145✔
59	}
60
61	/**
62	* The S3-compatible surface dispatches ~18 real commands (PutObject, ListObjects,
63	* CreateMultipartUpload, ...) from a handful of generic Fastify routes based on query
64	* string/header matching done entirely inside the internal `s3/router.ts` Router - see
65	* `s3/index.ts`. Fastify (and therefore @fastify/swagger) only ever sees the outer
66	* catch-all route with no request/response schema, since OpenAPI has no way to express
67	* "N distinct operations, same path and method, picked by a query parameter". Documenting
68	* that catch-all as-is would give SDK generators a single method with an untyped body and
69	* an untyped response for a request that's actually the whole S3 API - worse than nothing.
70	* Hide it instead; the real per-command schemas remain the source of truth in s3/commands/*.
71	*/
72	function isS3ProtocolCatchAll(schema: FastifySchema \| undefined, route: RouteOptions): boolean {
73	const operation = (route.config as { operation?: string } \| undefined)?.operation	161✔
74	return (schema?.tags?.includes('s3') ?? false) && !operation	161✔
75	}
76
77	/**
78	* Derives a stable, unique operationId from the route's `config.operation`
79	* (see ROUTE_OPERATIONS in ./operations.ts), e.g. `storage.object.get_public` -> `objectGetPublic`.
80	* Routes without a `config.operation` (protocol-level catch-alls like /s3 and /upload/resumable)
81	* are left without an operationId.
82	*/
83	function operationToId(operation: string): string {
84	const parts = operation.split('.').filter((part) => part !== 'storage')	195✔
85	return parts	63✔
86	.map((part) =>
87	part	138✔
88	.split('_')
89	.filter(Boolean)
90	.map((word, i) => (i === 0 ? word : word[0].toUpperCase() + word.slice(1)))	187✔
91	.join('')
92	)
93	.map((part, i) => (i === 0 ? part : part[0].toUpperCase() + part.slice(1)))	138✔
94	.join('')
95	}
96
97	/**
98	* Every route can end up hitting setErrorHandler and getting back a {statusCode, error,
99	* message, code} body (or, for a subtree with its own formatter, whatever that subtree
100	* documents instead) - default the doc to that shape for any otherwise-undocumented 4xx.
101	* Doc-only on purpose: several handlers reply with an ad-hoc, partial error body directly
102	* (`reply.status(400).send({message: '...'})`, bypassing the formatter entirely), and an
103	* earlier version of this defaulted via a real onRoute hook that made Fastify enforce
104	* errorSchema's `required` fields during response serialization - which threw on exactly
105	* those ad-hoc replies (fast-json-stringify errors on a missing required property rather
106	* than dropping it). A transform can't affect request handling, so it can't cause that.
107	*/
108	function defaultErrorResponse(schema: FastifySchema \| undefined): FastifySchema {
109	const response = schema?.response as Record<string, unknown> \| undefined	145✔
110	if (schema && response && Object.keys(response).some((status) => /^4xx$/i.test(status))) {	221✔
111	return schema	43✔
112	}
113
114	return {	102✔
115	...schema,
116	response: {
117	...(response ? undefined : { 200: { description: 'Default Response' } }),	102✔
118	'4xx': { description: 'Error response', $ref: 'errorSchema#' },
119	...response,
120	},
121	}
122	}
123
124	const MULTIPART_UPLOAD_OPERATIONS = new Set<string>([	38✔
125	ROUTE_OPERATIONS.CREATE_OBJECT,
126	ROUTE_OPERATIONS.UPDATE_OBJECT,
127	ROUTE_OPERATIONS.UPLOAD_SIGN_OBJECT,
128	])
129
130	/**
131	* createObject/updateObject/uploadSignedObject never set `schema.body` - they read the raw
132	* multipart stream directly via `uploadFromRequest` -> `fileUploadFromRequest`
133	* (see src/storage/object.ts), without registering `@fastify/multipart`'s
134	* `attachFieldsToBody`. That means `request.body` is always `undefined` on these routes, so a
135	* real `schema.body` would make Fastify validate that `undefined` (substituted as `null`)
136	* against a required-fields schema on every real upload and fail it with a 400 - a production
137	* regression, not a docs improvement. Document the multipart shape here instead, transform-only,
138	* where - like `defaultErrorResponse` above - it can never reach live request validation.
139	*/
140	function documentMultipartUploadBody(schema: FastifySchema, route: RouteOptions): FastifySchema {
141	const operation = (route.config as { operation?: string } \| undefined)?.operation	145✔
142	if (!operation \|\| !MULTIPART_UPLOAD_OPERATIONS.has(operation)) {	145✔
143	return schema	139✔
144	}
145
146	return {	6✔
147	...schema,
148	consumes: ['multipart/form-data'],
149	body: {
150	type: 'object',
151	properties: {
152	cacheControl: { type: 'string' },
153	metadata: { type: 'string' },
154	file: { type: 'string', contentEncoding: 'binary' },
155	},
156	required: ['cacheControl', 'file'],
157	},
158	}
159	}
160
161	/**
162	* OpenAPI requires operationId to be unique across the whole document. `exposeHeadRoutes`
163	* auto-derives a HEAD operation from every GET route re-using the same `config.operation`,
164	* so the id needs a per-method suffix to stay unique when that happens.
165	* Returns a fresh transform bound to its own dedup state, so main/admin specs don't
166	* leak collisions into each other when generated in the same process (see export-docs.ts).
167	*/
168	export function createOpenApiTransform() {
169	const seenIds = new Set<string>()	7✔
170
171	return function transformOpenApiSchema({	7✔
172	schema,
173	url,
174	route,
175	}: {
176	schema: FastifySchema
177	url: string
178	route: RouteOptions
179	}): { schema: FastifySchema; url: string } {
180	if (isS3ProtocolCatchAll(schema, route)) {	161✔
181	return { schema: { ...schema, hide: true }, url }	16✔
182	}
183
184	;({ schema, url } = renameWildcardParam(schema, url))	145✔
185	schema = defaultErrorResponse(schema)	145✔
186	schema = documentMultipartUploadBody(schema, route)	145✔
187
188	const operation = (route.config as { operation?: string } \| undefined)?.operation	145✔
189
190	if (!operation \|\| (schema as { operationId?: string }).operationId) {	161✔
191	return { schema, url }	82✔
192	}
193
194	const baseId = operationToId(operation)	63✔
195	let operationId = baseId	63✔
196	if (seenIds.has(operationId)) {	63✔
197	const method = Array.isArray(route.method) ? route.method[0] : route.method	19!
198	operationId = baseId + method[0].toUpperCase() + method.slice(1).toLowerCase()	19✔
199	}
200	for (let suffix = 2; seenIds.has(operationId); suffix++) {	63✔
201	operationId = baseId + suffix	2✔
202	}
203	seenIds.add(operationId)	63✔
204
205	return {	63✔
206	schema: { ...schema, operationId },
207	url,
208	}
209	}
210	}
211
212	/**
213	* A handful of paths are reachable both with and without a trailing slash - either because
214	* Fastify's own `exposeHeadRoutes` derives a HEAD route from the un-prefixed path (e.g.
215	* /health vs /health/) or because a route is explicitly registered both ways (the S3
216	* protocol surface). Both forms genuinely work at runtime, but documenting them as two
217	* unrelated paths just doubles the number of operations a generated SDK has to deal with
218	* for the same endpoint. Keep the slash-less form and fold the other one's methods into it.
219	*/
220	export const dedupeTrailingSlashPaths: SwaggerTransformObject = (documentObject) => {	38✔
221	if (!('openapiObject' in documentObject)) {	2!
NEW 222	return documentObject.swaggerObject	×
223	}
224
225	const { openapiObject } = documentObject	2✔
226	const paths = openapiObject.paths as Record<string, Record<string, unknown>> \| undefined	2✔
227	if (!paths) {	2!
NEW 228	return openapiObject	×
229	}
230
231	for (const url of Object.keys(paths)) {	2✔
232	if (url === '/' \|\| !url.endsWith('/')) {	55✔
233	continue	49✔
234	}
235
236	const canonicalUrl = url.slice(0, -1)	6✔
237	const canonicalPathItem = paths[canonicalUrl]	6✔
238	if (!canonicalPathItem) {	6✔
239	continue	3✔
240	}
241
242	for (const [method, operation] of Object.entries(paths[url])) {	3✔
243	canonicalPathItem[method] ??= operation	7✔
244	}
245	delete paths[url]	3✔
246	}
247
248	return openapiObject	2✔
249	}

supabase / storage / 31013736042

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous