Skip to content

Refactor Swagger to OpenAPI #235

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SaltyAom merged 8 commits into from
Sep 2, 2025
Merged

Refactor Swagger to OpenAPI #235

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5e58a60
:tada: feat: refactor
SaltyAom Sep 2, 2025
c3c91bb
:tada: feat: refactor
SaltyAom Sep 2, 2025
598fea4
:tada: feat: operationId per possible path
SaltyAom Sep 2, 2025
d028a9d
:tada: feat: operationId per possible path
SaltyAom Sep 2, 2025
2f1df4f
:tada: feat: generator
SaltyAom Sep 2, 2025
f410e31
:tada: feat: export generator
SaltyAom Sep 2, 2025
a49b0f0
:blue_book: doc: update doc from swagger to OpenAPI
SaltyAom Sep 2, 2025
3df25f4
Merge branch 'main' into hana
SaltyAom Sep 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`

Comment on lines +1 to +13
Copy link

@coderabbitai coderabbitai bot Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Document the breaking changes clearly but fix formatting issues.

The changelog properly documents the major refactoring from Swagger to OpenAPI, but there are formatting issues that need to be addressed.

Apply this diff to fix the formatting issues:

-# 1.3.2 - 22 Aug 2025
-Feature:
+# 1.3.2 - 22 Aug 2025
+Features:
 - 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:
+Breaking changes:
 - 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`
+- map `excludePaths`, `excludeMethods`, `excludeTags`, `excludeStaticFiles` to property of `excludes`

-# 1.3.1 - 28 Jun 2025
+# 1.3.1 - 28 Jun 2025
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# 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.2 - 22 Aug 2025
Features:
- 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 changes:
- 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
🧰 Tools
🪛 LanguageTool

[grammar] ~1-~1: There might be a mistake here.
Context: # 1.3.2 - 22 Aug 2025 Feature: - add withHeader for adding c...

(QB_NEW_EN)

🪛 markdownlint-cli2 (0.17.2)

12-12: Hard tabs
Column: 76

(MD010, no-hard-tabs)

🤖 Prompt for AI Agents 
In CHANGELOG.md around lines 1 to 13, tidy the formatting of the release notes:
ensure the top-level heading is "## 1.3.2 - 22 Aug 2025" (use a consistent
markdown header level), add blank lines between the header and sections, change
"Feature:" and "Breaking change:" to bold section headings like "### Features"
and "### Breaking changes", normalize bullet items to start with "- " and keep
code identifiers wrapped in backticks (e.g., `withHeader`, `toOpenAPI`), rename
"Breaking change:" to plural and make each mapping line consistent (e.g., "-
rename `@elysiajs/swagger` to `@elysiajs/openapi`"), fix the tab/spacing issue
on the last mapping line so it reads "- map `excludePaths`, `excludeMethods`,
`excludeTags`, `excludeStaticFiles` to properties of `excludes`", and ensure
consistent capitalization and punctuation across bullets.

# 1.3.1 - 28 Jun 2025
Bug fix:
- Using relative path for specPath

Expand Down
42 changes: 21 additions & 21 deletions build.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
90 changes: 55 additions & 35 deletions bun.lock
View file
Open in desktop

Large diffs are not rendered by default.

78 changes: 52 additions & 26 deletions example/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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'
})
})

const app = new Elysia()
.use(
swagger({
openapi({
provider: 'scalar',
documentation: {
info: {
title: 'Elysia Scalar',
version: '0.8.1'
version: '1.3.1a'
},
tags: [
{
Expand All @@ -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)
46 changes: 0 additions & 46 deletions example/index2.ts
View file
Open in desktop

This file was deleted.

60 changes: 0 additions & 60 deletions example/index3.ts
View file
Open in desktop

This file was deleted.

60 changes: 35 additions & 25 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "@elysiajs/swagger",
"version": "1.3.1",
"description": "Plugin for Elysia to auto-generate Swagger page",
"name": "@elysiajs/openapi",
"version": "1.3.2",
"description": "Plugin for Elysia to auto-generate OpenAPI documentation",
"author": {
"name": "saltyAom",
"url": "https://github.com/SaltyAom",
Expand All @@ -17,15 +17,10 @@
"import": "./dist/index.mjs",
"require": "./dist/cjs/index.js"
},
"./types": {
"types": "./dist/types.d.ts",
"import": "./dist/types.mjs",
"require": "./dist/cjs/types.js"
},
"./utils": {
"types": "./dist/utils.d.ts",
"import": "./dist/utils.mjs",
"require": "./dist/cjs/utils.js"
"./openapi": {
"types": "./dist/openapi.d.ts",
"import": "./dist/openapi.mjs",
"require": "./dist/cjs/openapi.js"
},
Comment on lines +25 to 29
Copy link

@coderabbitai coderabbitai bot Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Ensure subpath export "./openapi" is the documented entry.

Looks good; verify README and examples import from "@elysiajs/openapi/openapi".

🏁 Script executed:

#!/bin/bash
rg -nP "@elysiajs/(swagger|openapi)" -g 'README.md' -g 'docs/**' -S

Length of output: 194

🏁 Script executed:

#!/bin/bash
# Search for openapi references in all markdown files and examples directory
rg -nP "@elysiajs/openapi" -g '*.md' -S
rg -nP "@elysiajs/openapi" -g 'examples/**' -S

Length of output: 302

Update README and examples imports to use the new subpath
Replace all occurrences of @elysiajs/swagger in README.md (e.g. lines 1, 6, 12) with @elysiajs/openapi/openapi, and ensure any example files import from @elysiajs/openapi/openapi rather than the old package.

🤖 Prompt for AI Agents 
In package.json around lines 20 to 24, the package subpath was changed to
"./openapi" but README and example files still import from the old package name;
update README.md (e.g. lines 1, 6, 12) and all example source files to replace
any occurrences of "@elysiajs/swagger" with "@elysiajs/openapi/openapi" and
update import statements accordingly so examples import from
"@elysiajs/openapi/openapi" (ensure default/named import forms remain correct
and run a quick project-wide search to catch all occurrences).

"./scalar": {
"types": "./dist/scalar/index.d.ts",
Expand All @@ -36,18 +31,35 @@
"types": "./dist/scalar/theme.d.ts",
"import": "./dist/scalar/theme.mjs",
"require": "./dist/cjs/scalar/theme.js"
},
"./swagger": {
"types": "./dist/swagger/index.d.ts",
"import": "./dist/swagger/index.mjs",
"require": "./dist/cjs/swagger/index.js"
},
"./swagger/types": {
"types": "./dist/swagger/types.d.ts",
"import": "./dist/swagger/types.mjs",
"require": "./dist/cjs/swagger/types.js"
},
"./types": {
"types": "./dist/types.d.ts",
"import": "./dist/types.mjs",
"require": "./dist/cjs/types.js"
}
},
"keywords": [
"elysia",
"swagger"
"openapi",
"swagger",
"scalar"
],
"homepage": "https://github.com/elysiajs/elysia-swagger",
"homepage": "https://github.com/elysiajs/elysia-openapi",
"repository": {
"type": "git",
"url": "https://github.com/elysiajs/elysia-swagger"
"url": "https://github.com/elysiajs/elysia-openapi"
},
"bugs": "https://github.com/elysiajs/elysia-swagger/issues",
"bugs": "https://github.com/elysiajs/elysia-openapi/issues",
"license": "MIT",
Comment on lines +62 to 68
Copy link

@coderabbitai coderabbitai bot Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Repository/homepage/bugs URLs changed — validate correctness before release.

Avoid publishing with stale links.

🏁 Script executed:

#!/bin/bash
for u in \
  "https://github.com/elysiajs/elysia-openapi" \
  "https://github.com/elysiajs/elysia-openapi/issues"; do
  echo "Check: $u"
done

Length of output: 447

🏁 Script executed:

#!/bin/bash
for u in \
  "https://github.com/elysiajs/elysia-openapi" \
  "https://github.com/elysiajs/elysia-openapi/issues"; do
  echo "Checking: $u"
  curl -o /dev/null -s -w "HTTP %{http_code} - Final URL: %{url_effective}\n" -L "$u"
done

Length of output: 851

Broken homepage/repository/bugs URLs — update before release.
The URLs in package.json (lines 57–63) currently return HTTP 404. Replace them with the correct GitHub repository and issue-tracker links before publishing.

🤖 Prompt for AI Agents 
In package.json around lines 57 to 63, the homepage/repository/bugs URLs are
invalid and must be updated before release; replace "homepage",
"repository.url", and "bugs" with the correct GitHub repository URL and the
repository's issues URL (e.g., the canonical https://github.com/<org>/<repo> and
https://github.com/<org>/<repo>/issues), ensure "repository" remains an object
with type and url, and verify there are no trailing commas or malformed JSON
after the change.

"scripts": {
"dev": "bun run --watch example/index.ts",
Expand All @@ -60,17 +72,15 @@
"elysia": ">= 1.3.0"
},
"devDependencies": {
"@apidevtools/swagger-parser": "^10.1.0",
"@types/bun": "1.1.14",
"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",
"@scalar/types": "^0.0.12",
"openapi-types": "^12.1.3",
"pathe": "^1.1.2"
"openapi-types": "^12.1.3"
}
}
Loading