Merge pull request #235 from elysiajs/hana

Refactor Swagger to OpenAPI

Author: SaltyAom

CHANGELOG.md

@@ -1,4 +1,17 @@
-# 1.3.1
+# 1.3.2 - 22 Aug 2025
+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`
+- map all `swagger`, and `scalar` prefix to respective `swagger` and `scalar` properties
+- rename `swaggerConfig`, and `scalarConfig` to `swagger` and `scalar` respectively
+- map `excludePaths`, `excludeMethods`, `excludeTags`, `excludeStaticFiles`	 to property of `excludes`
+
+# 1.3.1 - 28 Jun 2025
 Bug fix:
 - Using relative path for specPath
 

README.md

@@ -1,18 +1,18 @@
-# @elysiajs/swagger
-Plugin for [elysia](https://github.com/elysiajs/elysia) to auto-generate Swagger page.
+# @elysiajs/openapi
+Plugin for [elysia](https://github.com/elysiajs/elysia) to auto-generate API documentation page.
 
 ## Installation
 ```bash
-bun add @elysiajs/swagger
+bun add @elysiajs/openapi
 ```
 
 ## Example
 ```typescript
 import { Elysia, t } from 'elysia'
-import { swagger } from '@elysiajs/swagger'
+import { openapi } from '@elysiajs/openapi'
 
 const app = new Elysia()
-    .use(swagger())
+    .use(openapi())
     .get('/', () => 'hi', { response: t.String({ description: 'sample description' }) })
     .post(
         '/json/:id',
@@ -43,34 +43,59 @@ const app = new Elysia()
     .listen(8080);
 ```
 
-Then go to `http://localhost:8080/swagger`.
+Then go to `http://localhost:8080/openapi`.
 
 # config
 
-## provider
-@default 'scalar'
-Choose between [Scalar](https://github.com/scalar/scalar) & [SwaggerUI](https://github.com/swagger-api/swagger-ui)
+## enabled
+@default true
+Enable/Disable the plugin
 
-## scalar
-Customize scalarConfig, refers to [Scalar config](https://github.com/scalar/scalar/blob/main/documentation/configuration.md)
+## documentation
+OpenAPI documentation information
 
-## swagger
-Customize Swagger config, refers to [Swagger 3.0.3 config](https://swagger.io/specification/v3)
+@see https://spec.openapis.org/oas/v3.0.3.html
 
-## path
-@default '/swagger'
+## exclude
+Configuration to exclude paths or methods from documentation
 
-The endpoint to expose Swagger
+## exclude.methods
+List of methods to exclude from documentation
 
-## scalarCDN
-Self-host the scalar bundle or point to a different CDN.
+## exclude.paths
+List of paths to exclude from documentation
 
-## excludeStaticFile
+## exclude.staticFile
 @default true
 
-Determine if Swagger should exclude static files.
+Exclude static file routes from documentation
 
-## exclude
-@default []
+## exclude.tags
+List of tags to exclude from documentation
+
+## path
+@default '/openapi'
+
+The endpoint to expose OpenAPI documentation frontend
 
-Paths to exclude from the Swagger endpoint
+## provider
+@default 'scalar'
+
+OpenAPI documentation frontend between:
+- [Scalar](https://github.com/scalar/scalar)
+- [SwaggerUI](https://github.com/openapi-api/openapi-ui)
+- null: disable frontend
+
+## references
+Additional OpenAPI reference for each endpoint
+
+## scalar
+Scalar configuration, refers to [Scalar config](https://github.com/scalar/scalar/blob/main/documentation/configuration.md)
+
+## specPath
+@default '/${path}/json'
+
+The endpoint to expose OpenAPI specification in JSON format
+
+## swagger
+Swagger config, refers to [Swagger config](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/)

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

@@ -0,0 +1,22 @@
+import { Elysia, t } from 'elysia'
+import { openapi } from '../src/index'
+import { fromTypes } from '../src/gen'
+
+export const app = new Elysia()
+	.use(
+		openapi({
+			references: fromTypes('example/gen.ts')
+		})
+	)
+	.get('/', { test: 'hello' as const })
+	.post(
+		'/json',
+		({ body, status }) => (Math.random() > 0.5 ? status(418) : body),
+		{
+			body: t.Object({
+				hello: t.String()
+			})
+		}
+	)
+	.get('/id/:id/name/:name', ({ params }) => params)
+	.listen(3000)

example/gen.ts

@@ -1,18 +1,28 @@
 import { Elysia, t } from 'elysia'
-import { swagger } from '../src/index'
+import { openapi, withHeaders } from '../src/index'
 
 const schema = t.Object({
 	test: t.Literal('hello')
 })
 
-const app = new Elysia({ prefix: '/api' })
+const schema2 = t.Object({
+	test: t.Literal('world')
+})
+
+const user = t.Object({
+	name: t.String({
+		example: 'saltyaom'
+	})
+})
+
+export const app = new Elysia()
 	.use(
-		swagger({
+		openapi({
 			provider: 'scalar',
 			documentation: {
 				info: {
 					title: 'Elysia Scalar',
-					version: '0.8.1'
+					version: '1.3.1a'
 				},
 				tags: [
 					{
@@ -21,39 +31,55 @@ const app = new Elysia({ prefix: '/api' })
 					}
 				],
 				components: {
-					schemas: {
-						User: {
-							description: 'string'
-						}
-					},
 					securitySchemes: {
-						JwtAuth: {
+						bearer: {
 							type: 'http',
-							scheme: 'bearer',
-							bearerFormat: 'JWT',
-							description: 'Enter JWT Bearer token **_only_**'
+							scheme: 'bearer'
+						},
+						cookie: {
+							type: 'apiKey',
+							in: 'cookie',
+							name: 'session_id'
 						}
 					}
 				}
-			},
-			swaggerOptions: {
-				persistAuthorization: true
 			}
 		})
 	)
-	.model({ schema })
+	.model({ schema, schema2, user })
 	.get(
 		'/',
-		() => {
-			return { test: 'hello' as const }
-		},
+		{ test: 'hello' as const },
+		{
+			response: {
+				200: t.Object({
+					test: t.Literal('hello')
+				}),
+				204: withHeaders(
+					t.Void({
+						title: 'Thing',
+						description: 'Void response'
+					}),
+					{
+						'X-Custom-Header': t.Literal('Elysia')
+					}
+				)
+			}
+		}
+	)
+	.post(
+		'/json',
+		({ body }) => ({
+			test: 'world'
+		}),
 		{
-			response: 'schema'
+			parse: ['json', 'formdata'],
+			body: 'user',
+			response: {
+				200: 'schema',
+				400: 'schema2'
+			}
 		}
 	)
-	.post('/json', ({ body }) => body, {
-		parse: ['json', 'formdata'],
-		body: 'schema',
-		response: 'schema'
-	})
+	.get('/id/:id/name/:name', () => {})
 	.listen(3000)