remove documentation endpoint

.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

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

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"

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}`);

src/server/documentation.ts → 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')
-		})
-	);
 };

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;