🎉 feat: operationId per possible path

Author: SaltyAom

CHANGELOG.md

@@ -2,6 +2,8 @@
 Feature:
 - add `withHeader` for adding custom headers to response schema
 - spread all possible path for optional params
+- provider can be `null` to disable provider
+- export `toOpenAPI` to generate spec programmatically
 
 Breaking change:
 - rename `@elysiajs/swagger` to `@elysiajs/openapi`

build.ts

@@ -4,30 +4,30 @@ import { build, type Options } from 'tsup'
 await $`rm -rf dist`
 
 const tsupConfig: Options = {
-    entry: ['src/**/*.ts'],
-    splitting: false,
-    sourcemap: false,
-    clean: true,
-    bundle: true
+	entry: ['src/**/*.ts'],
+	splitting: false,
+	sourcemap: false,
+	clean: true,
+	bundle: true
 } satisfies Options
 
 await Promise.all([
-    // ? tsup esm
-    build({
-        outDir: 'dist',
-        format: 'esm',
-        target: 'node20',
-        cjsInterop: false,
-        ...tsupConfig
-    }),
-    // ? tsup cjs
-    build({
-        outDir: 'dist/cjs',
-        format: 'cjs',
-        target: 'node20',
-        // dts: true,
-        ...tsupConfig
-    })
+	// ? tsup esm
+	build({
+		outDir: 'dist',
+		format: 'esm',
+		target: 'node20',
+		cjsInterop: false,
+		...tsupConfig
+	}),
+	// ? tsup cjs
+	build({
+		outDir: 'dist/cjs',
+		format: 'cjs',
+		target: 'node20',
+		// dts: true,
+		...tsupConfig
+	})
 ])
 
 await $`tsc --project tsconfig.dts.json`

bun.lock

@@ -61,7 +61,7 @@ const app = new Elysia()
 						description: 'Void response'
 					}),
 					{
-						'X-Custom-Header': t.String()
+						'X-Custom-Header': t.Literal('Elysia')
 					}
 				)
 			}

example/index.ts

@@ -72,16 +72,15 @@
         "elysia": ">= 1.3.0"
     },
     "devDependencies": {
-        "@apidevtools/swagger-parser": "^10.1.0",
-        "@types/bun": "1.1.14",
-        "@scalar/types": "^0.0.12",
-        "elysia": "1.3.0-exp.71",
+        "@apidevtools/swagger-parser": "^12.0.0",
+        "@types/bun": "1.2.20",
+        "@scalar/types": "^0.2.13",
+        "elysia": "1.3.21",
         "eslint": "9.6.0",
-        "tsup": "^8.1.0",
-        "typescript": "^5.5.3"
+        "tsup": "^8.5.0",
+        "typescript": "^5.9.2"
     },
     "dependencies": {
-        "@scalar/themes": "^0.9.52",
         "openapi-types": "^12.1.3"
     }
 }

package.json

@@ -6,38 +6,29 @@ import { ScalarRender } from './scalar'
 import { toOpenAPISchema } from './openapi'
 
 import type { OpenAPIV3 } from 'openapi-types'
-import type { ReferenceConfiguration } from '@scalar/types'
+import type { ApiReferenceConfiguration } from '@scalar/types'
 import type { ElysiaOpenAPIConfig, OpenAPIProvider } from './types'
 
 /**
- * Plugin for [elysia](https://github.com/elysiajs/elysia) that auto-generate Swagger page.
+ * Plugin for [elysia](https://github.com/elysiajs/elysia) that auto-generate OpenAPI documentation page.
  *
  * @see https://github.com/elysiajs/elysia-swagger
  */
 export const openapi = <
+	const Enabled extends boolean = true,
 	const Path extends string = '/openapi',
 	const Provider extends OpenAPIProvider = 'scalar'
 >({
-	provider = 'scalar',
+	enabled = true as Enabled,
 	path = '/openapi' as Path,
+	provider = 'scalar' as Provider,
 	specPath = `${path}/json`,
 	documentation = {},
 	exclude,
 	swagger,
 	scalar
-}: ElysiaOpenAPIConfig<Path, Provider> = {}) => {
-	const {
-		version: swaggerVersion = '5.9.0',
-		theme: swaggerTheme = `https://unpkg.com/swagger-ui-dist@${swaggerVersion}/swagger-ui.css`,
-		autoDarkMode = true,
-		...swaggerOptions
-	} = swagger ?? {}
-
-	const {
-		version: scalarVersion = 'latest',
-		cdn: scalarCDN = '',
-		...scalarConfig
-	} = scalar ?? {}
+}: ElysiaOpenAPIConfig<Enabled, Path, Provider> = {}) => {
+	if (!enabled) return new Elysia({ name: '@elysiajs/openapi' })
 
 	const info = {
 		title: 'Elysia Documentation',
@@ -51,46 +42,28 @@ export const openapi = <
 	let totalRoutes = 0
 	let cachedSchema: OpenAPIV3.Document | undefined
 
-	const app = new Elysia({ name: '@elysiajs/swagger' })
+	const app = new Elysia({ name: '@elysiajs/openapi' })
 		.use((app) => {
 			if (provider === null) return app
 
 			return app.get(
 				path,
 				new Response(
 					provider === 'swagger-ui'
-						? SwaggerUIRender(
-								info,
-								swaggerVersion,
-								swaggerTheme,
-								JSON.stringify(
-									{
-										url: relativePath,
-										dom_id: '#swagger-ui',
-										...swaggerOptions
-									},
-									(_, value) =>
-										typeof value === 'function'
-											? undefined
-											: value
-								),
-								autoDarkMode
-							)
-						: ScalarRender(
-								info,
-								scalarVersion,
-								{
-									spec: {
-										url: relativePath,
-										...scalarConfig.spec
-									},
-									...scalarConfig,
-									// so we can showcase the elysia theme
-									// @ts-expect-error
-									_integration: 'elysiajs'
-								} satisfies ReferenceConfiguration,
-								scalarCDN
-							),
+						? SwaggerUIRender(info, {
+								url: relativePath,
+								dom_id: '#swagger-ui',
+								version: 'latest',
+								autoDarkMode: true,
+								...swagger
+							})
+						: ScalarRender(info, {
+								url: relativePath,
+								version: 'latest',
+								cdn: `https://cdn.jsdelivr.net/npm/@scalar/api-reference@${scalar?.version ?? 'latest'}/dist/browser/standalone.min.js`,
+								...(scalar as ApiReferenceConfiguration),
+								_integration: 'elysiajs'
+							}),
 					{
 						headers: {
 							'content-type': 'text/html; charset=utf8'
@@ -155,4 +128,5 @@ export const openapi = <
 
 export { toOpenAPISchema, withHeaders } from './openapi'
 export type { ElysiaOpenAPIConfig }
+
 export default openapi

src/index.ts

@@ -17,10 +17,9 @@ const toOperationId = (method: string, paths: string) => {
 	if (!paths || paths === '/') return operationId + 'Index'
 
 	for (const path of paths.split('/'))
-		operationId +=
-			path.charCodeAt(0) === 123
-				? 'By' + capitalize(path.slice(1, -1))
-				: capitalize(path)
+		operationId += path.includes(':')
+			? 'By' + capitalize(path.replace(':', ''))
+			: capitalize(path)
 
 	operationId = operationId.replace(/\?/g, 'Optional')
 
@@ -71,7 +70,7 @@ export function toOpenAPISchema(
 			? [exclude.paths]
 			: []
 
-	const paths: OpenAPIV3.PathsObject = {}
+	const paths: OpenAPIV3.PathsObject = Object.create(null)
 
 	// @ts-ignore private property
 	const routes = app.getGlobalRoutes()
@@ -260,7 +259,8 @@ export function toOpenAPISchema(
 				for (let [status, schema] of Object.entries(hooks.response)) {
 					if (typeof schema === 'string') schema = toRef(schema)
 
-					const { type, examples, ...options } = schema
+					// Must exclude $ref from root options
+					const { type, examples, $ref, ...options } = schema
 
 					operation.responses[status] = {
 						description: `Response for status ${status}`,
@@ -294,7 +294,7 @@ export function toOpenAPISchema(
 		}
 
 		for (let path of getPossiblePath(route.path)) {
-			const operationId = toOperationId(route.method, route.path)
+			const operationId = toOperationId(route.method, path)
 
 			path = path.replace(/:([^/]+)/g, '{$1}')
 
@@ -311,11 +311,20 @@ export function toOpenAPISchema(
 			}
 
 			// Handle 'ALL' method by assigning operation to all standard methods
-			for(const method of ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'trace'])
-			current[method] = {
-				...operation,
-				operationId
-			}
+			for (const method of [
+				'get',
+				'post',
+				'put',
+				'delete',
+				'patch',
+				'head',
+				'options',
+				'trace'
+			])
+				current[method] = {
+					...operation,
+					operationId
+				}
 		}
 	}