📘 doc: update doc from swagger to OpenAPI

Author: SaltyAom

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,31 +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
+
+## exclude.methods
+List of methods to exclude from documentation
 
-The endpoint to expose Swagger
+## 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'
 
-Paths to exclude from the Swagger endpoint
+The endpoint to expose OpenAPI documentation frontend
+
+## 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/)

package.json

@@ -1,7 +1,7 @@
 {
     "name": "@elysiajs/openapi",
     "version": "1.3.2",
-    "description": "Plugin for Elysia to auto-generate OpenAPI documentation",
+    "description": "Plugin for Elysia to auto-generate API documentation",
     "author": {
         "name": "saltyAom",
         "url": "https://github.com/SaltyAom",

src/gen/index.ts

@@ -179,7 +179,7 @@ export const fromTypes =
 
 				if (!routes[path]) routes[path] = {}
 				// @ts-ignore
-				routes[path][method] = schema
+				routes[path][method.toLowerCase()] = schema
 			}
 
 			return routes

src/openapi.ts

@@ -95,8 +95,12 @@ export function toOpenAPISchema(
 
 		const method = route.method.toLowerCase()
 
-		if (excludePaths.includes(route.path)) continue
-		if (excludeMethods.includes(method)) continue
+		if (
+			(excludeStaticFile && route.path.includes('.')) ||
+			excludePaths.includes(route.path) ||
+			excludeMethods.includes(method)
+		)
+			continue
 
 		const hooks: InputSchema & {
 			detail: Partial<OpenAPIV3.OperationObject>

src/types.ts

@@ -34,15 +34,49 @@ export interface ElysiaOpenAPIConfig<
 	enabled?: Enabled
 
 	/**
-	 * Customize Swagger config, refers to Swagger 2.0 config
+	 * OpenAPI config
 	 *
-	 * @see https://swagger.io/specification/v2/
+	 * @see https://spec.openapis.org/oas/v3.0.3.html
 	 */
 	documentation?: Omit<
 		Partial<OpenAPIV3.Document>,
 		| 'x-express-openapi-additional-middleware'
 		| 'x-express-openapi-validation-strict'
 	>
+
+	exclude?: {
+		/**
+		 * Exclude methods from OpenAPI
+		 */
+		methods?: string[]
+
+		/**
+		 * Paths to exclude from OpenAPI endpoint
+		 *
+		 * @default []
+		 */
+		paths?: string | RegExp | (string | RegExp)[]
+
+		/**
+		 * Determine if OpenAPI should exclude static files.
+		 *
+		 * @default true
+		 */
+		staticFile?: boolean
+
+		/**
+		 * Exclude tags from OpenAPI
+		 */
+		tags?: string[]
+	}
+
+	/**
+	 * The endpoint to expose OpenAPI Documentation
+	 *
+	 * @default '/openapi'
+	 */
+	path?: Path
+
 	/**
 	 * Choose your provider, Scalar or Swagger UI
 	 *
@@ -51,6 +85,12 @@ export interface ElysiaOpenAPIConfig<
 	 * @see https://github.com/swagger-api/swagger-ui
 	 */
 	provider?: Provider
+
+	/**
+	 * Additional reference for each endpoint
+	 */
+	references?: AdditionalReferences
+
 	/**
 	 * Scalar configuration to customize scalar
 	 *'
@@ -78,18 +118,13 @@ export interface ElysiaOpenAPIConfig<
 		 */
 		cdn?: string
 	}
-	/**
-	 * The endpoint to expose OpenAPI Documentation
-	 *
-	 * @default '/openapi'
-	 */
-	path?: Path
 	/**
 	 * The endpoint to expose OpenAPI JSON specification
 	 *
 	 * @default '/${path}/json'
 	 */
 	specPath?: string
+
 	/**
 	 * Options to send to SwaggerUIBundle
 	 * Currently, options that are defined as functions such as requestInterceptor
@@ -142,29 +177,4 @@ export interface ElysiaOpenAPIConfig<
 		 */
 		cdn?: string
 	}
-
-	exclude?: {
-		/**
-		 * Paths to exclude from OpenAPI endpoint
-		 *
-		 * @default []
-		 */
-		paths?: string | RegExp | (string | RegExp)[]
-		/**
-		 * Exclude methods from OpenAPI
-		 */
-		methods?: string[]
-		/**
-		 * Exclude tags from OpenAPI
-		 */
-		tags?: string[]
-		/**
-		 * Determine if OpenAPI should exclude static files.
-		 *
-		 * @default true
-		 */
-		staticFile?: boolean
-	}
-
-	references?: AdditionalReferences
 }