diff --git a/.env.example b/.env.example index 5cdebb2..a4c2275 100644 --- a/.env.example +++ b/.env.example @@ -13,13 +13,6 @@ # Is website served over HTTPS? [true]:boolean #TLS=true -## DOCUMENTATION: -# Enable documentation? [false]:boolean -#DOCS_ENABLED=false - -# Path to documentation [/docs]:string -#DOCS_PATH=/docs - ## DOCUMENT: # Maximum document size in kilobytes [1024]:integer #DOCUMENT_MAXSIZE=1024 \ No newline at end of file diff --git a/README.md b/README.md index 2803c91..a7c7c2e 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ docker run -e DOCS_ENABLED=true -d -p 127.0.0.1:4000:4000 \ ## Validate > [!IMPORTANT] -> ALL artifacts and images originate from GitHub `JSPaste/Backend` repository, no other artifacts or +> All artifacts and images originate from GitHub `JSPaste/Backend` repository, no other artifacts or > images built and distributed outside that repository are considered secure nor trusted by the JSPaste team. Artifacts are attested and can be verified using the following command: @@ -57,6 +57,23 @@ at [JSPaste Attestations](https://github.com/jspaste/backend/attestations). ## Development +### API + +The API is documented under OpenAPI specification and can be found at the following path: + +```shell +/:apipath/oas.json +``` + +There are several ways to interact with the API, we will cover its use with [Scalar](https://scalar.com). + +We recommend using the desktop application, however, +you can also use the [web-based environment](https://client.scalar.com). (you may need to disable the CORS Proxy) + +Follow these steps to import the instance's `oas.json` to Scalar: + +![](https://static.x.inetol.net/jspaste/backend/scalar-t1.gif) + ### Maintenance Over time, local repositories can become messy with untracked files, registered hooks, and temporary files in the .git diff --git a/bun.lockb b/bun.lockb index c8aa1d9..46ea48c 100755 Binary files a/bun.lockb and b/bun.lockb differ diff --git a/package.json b/package.json index 9f81a52..c34cf48 100644 --- a/package.json +++ b/package.json @@ -31,7 +31,6 @@ "start:server": "bun run ./dist/server.js" }, "dependencies": { - "@hono/swagger-ui": "~0.4.1", "@hono/zod-openapi": "~0.18.0", "env-var": "~7.5.0", "hono": "~4.6.10" diff --git a/src/server.ts b/src/server.ts index 60a1cf8..26fd687 100644 --- a/src/server.ts +++ b/src/server.ts @@ -1,11 +1,11 @@ import { OpenAPIHono } from '@hono/zod-openapi'; +import { oas } from '@x-server/oas.ts'; import { env } from '@x-util/env.ts'; import { logger } from '@x-util/logger.ts'; import { serve } from 'bun'; import { cors } from 'hono/cors'; import { HTTPException } from 'hono/http-exception'; import { config } from './config.ts'; -import { documentation } from './server/documentation.ts'; import { endpoints } from './server/endpoints.ts'; import { errorHandler } from './server/errorHandler.ts'; import { ErrorCode } from './types/ErrorHandler.ts'; @@ -32,8 +32,8 @@ export const server = (): typeof instance => { return ctx.body(null, 404); }); + oas(instance); endpoints(instance); - env.docsEnabled && documentation(instance); logger.debug('Registered routes:', instance.routes); logger.info(`Listening on: http://localhost:${env.port}`); diff --git a/src/server/documentation.ts b/src/server/oas.ts similarity index 77% rename from src/server/documentation.ts rename to src/server/oas.ts index 303b67f..64db10a 100644 --- a/src/server/documentation.ts +++ b/src/server/oas.ts @@ -1,9 +1,7 @@ -import { swaggerUI } from '@hono/swagger-ui'; import type { OpenAPIHono } from '@hono/zod-openapi'; -import { env } from '@x-util/env.ts'; import { config } from '../config.ts'; -export const documentation = (instance: OpenAPIHono): void => { +export const oas = (instance: OpenAPIHono): void => { instance.doc31('/oas.json', (ctx) => ({ openapi: '3.1.0', info: { @@ -30,11 +28,4 @@ export const documentation = (instance: OpenAPIHono): void => { } ].filter((server, index, self) => self.findIndex((x) => x.url === server.url) === index) })); - - instance.get( - env.docsPath, - swaggerUI({ - url: config.apiPath.concat('/oas.json') - }) - ); }; diff --git a/src/utils/env.ts b/src/utils/env.ts index d544187..6e98b71 100644 --- a/src/utils/env.ts +++ b/src/utils/env.ts @@ -2,10 +2,8 @@ import { LogLevels } from '@x-util/logger.ts'; import { get } from 'env-var'; export const env = { - port: get('PORT').default(4000).asPortNumber(), - logLevel: get('LOGLEVEL').default(LogLevels.info).asIntPositive(), - tls: get('TLS').asBoolStrict() ?? true, documentMaxSize: get('DOCUMENT_MAXSIZE').default(1024).asIntPositive(), - docsEnabled: get('DOCS_ENABLED').asBoolStrict() ?? false, - docsPath: get('DOCS_PATH').default('/docs').asString() + logLevel: get('LOGLEVEL').default(LogLevels.info).asIntPositive(), + port: get('PORT').default(4000).asPortNumber(), + tls: get('TLS').asBoolStrict() ?? true } as const;