@trojs/openapi-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TroJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# OpenAPI server
+
+[![NPM version][npm-image]][npm-url] [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-server&metric=coverage)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-server) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-server&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-server) 
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-server&metric=bugs)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-server) [![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-server&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-server) [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-server&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-server) [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-server&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-server)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-server&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-server) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-server&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-server) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-server&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-server)
+
+Create easy a webserver API first with a OpenAPI spec.
+
+## Installation
+
+`npm install @trojs/openapi-server`
+or
+`yarn add @trojs/openapi-server`
+
+## Test the package
+
+`npm run test`
+or
+`yarn test`
+
+## How to use
+
+```javascript
+
+const controllers = {
+    // connect to a openationId in the OpenAPI spec with the same name
+    getTest: ({
+        context,
+        request,
+        response,
+        parameters,
+        specification,
+        url
+      }) => ({ //response an object
+        test: 'ok'
+    })
+}
+
+const { openAPISpecification, Api } = await openAPI({ file: './openapi-spec.json', base })
+const api = new Api({
+  version: 'v1',
+  specification: openAPISpecification,
+  controllers,
+  secret: 'test',
+  logger: console
+})
+const { app } = await setupServer({
+  env: process.env,
+  apis: [api]
+})
+
+```
+
+If you create a controller, you can easy connect it to the operationId in the OpenAPI spec.
+Check also the examples in the test files.
+In your controller you can use e.g. context, request and response, from express.
+It isn neccesary to define it in your controller, if you don't use it, you can remove it.
+e.g.
+```javascript
+getTest: ({ parameters }) => 
+    {
+        return {
+            test: 'ok'
+        }
+    }
+```
+
+parameters are query param's from the url of a get request, parsed by the type defined in the OpenAPI spec.
+
+Specifications is the OpenAPI spec.
+
+Url is the current url.
+
+
+## Add custom security handlers like JWT
+```javascript
+import jwt from 'jsonwebtoken'
+
+function jwtHandler(context, request, response) {
+  const authHeader = context.request.headers.authorization;
+  if (!authHeader) {
+    throw new Error('Missing authorization header');
+  }
+  const token = authHeader.replace('Bearer ', '');
+  return jwt.verify(token, 'secret');
+}
+
+const securityHandlers = [
+  {
+    name: 'jwt',
+    handler: jwtHandler
+  }
+]
+
+const api = new Api({
+  version: 'v1',
+  specification: openAPISpecification,
+  controllers,
+  securityHandlers
+})
+```
+
+See also: https://openapistack.co/docs/openapi-backend/security-handlers/#security-handlers
+
+
+[npm-url]: https://www.npmjs.com/package/@trojs/openapi-server
+[npm-image]: https://img.shields.io/npm/v/@trojs/openapi-server.svg

package/package.json

@@ -0,0 +1,79 @@
+{
+    "name": "@trojs/openapi-server",
+    "description": "OpenAPI Server",
+    "version": "1.0.0",
+    "author": {
+        "name": "Pieter Wigboldus",
+        "url": "https://trojs.org/"
+    },
+    "license": "MIT",
+    "scripts": {
+        "lint": "eslint src/*.js --config .eslintrc",
+        "lint:report": "eslint src/*.js --config .eslintrc -f json -o report.json",
+        "lint:fix": "eslint src/*.js --config .eslintrc --fix",
+        "test": "c8 node --test src/*.test.js",
+        "cpd": "node_modules/jscpd/bin/jscpd src",
+        "vulnerabilities": "npm audit --omit=dev"
+    },
+    "type": "module",
+    "files": [
+        "src/api.js",
+        "src/openapi.js",
+        "src/router.js",
+        "src/server.js",
+        "src/error-status.js",
+        "src/types.js",
+        "src/params.js",
+        "src/express-callback.js",
+        "src/operation-ids.js",
+        "src/handlers/not-found.js",
+        "src/handlers/request-validation.js",
+        "src/handlers/response-validation.js",
+        "src/handlers/unauthorized.js"
+    ],
+    "main": "src/server.js",
+    "devDependencies": {
+        "@hckrnews/eslint-config": "^3.0.0",
+        "@types/express-serve-static-core": "^4.17.41",
+        "c8": "^9.0.0",
+        "eslint": "^8.23.0",
+        "eslint-config-standard": "^17.1.0",
+        "eslint-plugin-import": "^2.26.0",
+        "eslint-plugin-jsdoc": "^48.0.0",
+        "eslint-plugin-n": "^16.0.0",
+        "eslint-plugin-promise": "^6.0.1",
+        "eslint-plugin-sonarjs": "^0.25.1",
+        "jscpd": "^3.2.1",
+        "supertest": "^6.3.3"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/hckrnews/openapi-server"
+    },
+    "engines": {
+        "node": ">= 18.13"
+    },
+    "keywords": [
+        "openapi",
+        "server",
+        "express"
+    ],
+    "dependencies": {
+        "@sentry/node": "^7.86.0",
+        "ajv-formats": "^3.0.0",
+        "body-parser": "^1.20.2",
+        "compression": "^1.7.4",
+        "cors": "^2.8.5",
+        "express": "^4.19.2",
+        "helmet": "^7.0.0",
+        "openapi-backend": "^5.9.2",
+        "swagger-ui-express": "^5.0.0"
+    },
+    "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/w3nl"
+    },
+    "overrides": {
+        "semver": "^7.5.3"
+    }
+}

package/src/api.js

@@ -0,0 +1,76 @@
+import express from 'express'
+import swaggerUi from 'swagger-ui-express'
+import { setupRouter } from './router.js'
+
+/**
+ * @typedef {import('openapi-backend').Handler} Handler
+ * @typedef {object} Logger
+ * @property {Function} error
+ * @property {Function} warn
+ * @property {Function} info
+ * @property {Function} debug
+ * @typedef {object} SecurityHandler
+ * @property {string} name
+ * @property {Handler} handler
+ * @typedef {object} ApiSchema
+ * @property {string} version
+ * @property {object} specification
+ * @property {object} controllers
+ * @property {string=} secret
+ * @property {string=} apiRoot
+ * @property {boolean=} strictSpecification
+ * @property {boolean=} errorDetails
+ * @property {Logger=} logger
+ * @property {object=} meta
+ * @property {SecurityHandler[]=} securityHandlers
+ */
+
+/**
+ * Setup the server for a specific API, so every server can run multiple instances of the API, like different versions, for e.g. different clients
+ * @class
+ */
+export class Api {
+  /**
+   * @param {ApiSchema} params
+   */
+  constructor ({ version, specification, controllers, secret, apiRoot, strictSpecification, errorDetails, logger, meta, securityHandlers }) {
+    this.version = version
+    this.specification = specification
+    this.controllers = controllers
+    this.secret = secret
+    this.apiRoot = apiRoot
+    this.strictSpecification = strictSpecification
+    this.errorDetails = errorDetails || false
+    this.logger = logger || console
+    this.meta = meta || {}
+    this.securityHandlers = securityHandlers || []
+  }
+
+  setup () {
+    const router = express.Router()
+
+    router.use('/swagger', swaggerUi.serveFiles(this.specification, {}), swaggerUi.setup(this.specification))
+    router.get('/api-docs', (_request, response) =>
+      response.json(this.specification)
+    )
+
+    const { api } = setupRouter({
+      secret: this.secret,
+      openAPISpecification: this.specification,
+      controllers: this.controllers,
+      apiRoot: this.apiRoot,
+      strictSpecification: this.strictSpecification,
+      errorDetails: this.errorDetails,
+      logger: this.logger,
+      meta: this.meta,
+      securityHandlers: this.securityHandlers
+    })
+    api.init()
+
+    router.use((request, response) =>
+      api.handleRequest(request, request, response)
+    )
+
+    return router
+  }
+}

package/src/error-status.js

@@ -0,0 +1,24 @@
+const errorCodesStatus = [
+  {
+    type: TypeError,
+    status: 422
+  },
+  {
+    type: RangeError,
+    status: 404
+  },
+  {
+    type: Error,
+    status: 500
+  }
+]
+
+/**
+ * Get a http status when you send an error.
+ * When it is a error, throw back the error.
+ * @param {Error} error
+ * @returns {number}
+ */
+export default (error) =>
+  errorCodesStatus.find((errorCode) => error instanceof errorCode.type)
+    .status

package/src/express-callback.js

@@ -0,0 +1,91 @@
+import getStatusByError from './error-status.js'
+import { parseParams } from './params.js'
+
+/**
+ * @typedef {import('express-serve-static-core').Request} Request
+ * @typedef {import('express-serve-static-core').Response} Response
+ * @typedef {import('openapi-backend').Context} Context
+ * @typedef {import('./api.js').Logger} Logger
+ * @param {object} params
+ * @param {Function} params.controller
+ * @param {object} params.specification
+ * @param {boolean=} params.errorDetails
+ * @param {Logger=} params.logger
+ * @param {object=} params.meta
+ * @returns {(context: object, request: object, response: object) => Promise<any>}
+ */
+export const makeExpressCallback = ({
+  controller,
+  specification,
+  errorDetails,
+  logger,
+  meta
+}) =>
+/**
+ * Handle controller
+ * @async
+ * @param {Context} context
+ * @param {Request} request
+ * @param {Response} response
+ * @returns {Promise<any>}
+ */
+  async (context, request, response) => {
+    try {
+      const allParameters = {
+        ...(context.request?.params || {}),
+        ...(context.request?.query || {})
+      }
+      const parameters = parseParams({
+        query: allParameters,
+        spec: context.operation.parameters
+      })
+      const url = `${request.protocol}://${request.get('Host')}${request.originalUrl}`
+
+      const responseBody = await controller({
+        context,
+        request,
+        response,
+        parameters,
+        specification,
+        post: request.body,
+        url,
+        logger,
+        meta
+      })
+      logger.debug({
+        url,
+        parameters,
+        post: request.body,
+        response: responseBody
+      })
+
+      return responseBody
+    } catch (error) {
+      const errorCodeStatus = getStatusByError(error)
+
+      logger.error(error)
+
+      response.status(errorCodeStatus)
+
+      if (errorDetails) {
+        return {
+          errors: [
+            {
+              message: error.message,
+              value: error.valueOf(),
+              type: error.constructor.name
+            }
+          ],
+          status: errorCodeStatus,
+          timestamp: new Date(),
+          message: error.message
+        }
+      }
+
+      return {
+        status: errorCodeStatus,
+        timestamp: new Date(),
+        message: error.message
+      }
+    }
+  }

package/src/handlers/not-found.js

@@ -0,0 +1,8 @@
+export const notFound = (_context, request, response) => {
+  response.status(404)
+  return {
+    status: 404,
+    timestamp: new Date(),
+    message: 'Not found'
+  }
+}

package/src/handlers/request-validation.js

@@ -0,0 +1,9 @@
+export const requestValidation = (context, request, response) => {
+  response.status(400)
+  return {
+    errors: context.validation.errors,
+    status: 400,
+    timestamp: new Date(),
+    message: 'Bad Request'
+  }
+}

package/src/handlers/response-validation.js

@@ -0,0 +1,30 @@
+export const responseValidation = (context, request, response) => {
+  const responseDoesntNeedValidation = response.statusCode >= 400
+  if (responseDoesntNeedValidation) {
+    return response.json(context.response)
+  }
+
+  const valid = context.api.validateResponse(
+    context.response,
+    context.operation
+  )
+  if (valid?.errors) {
+    return response.status(502).json({
+      errors: valid.errors,
+      status: 502,
+      timestamp: new Date(),
+      message: 'Bad response'
+    })
+  }
+
+  if (!context.response) {
+    return response.end()
+  }
+
+  const contentType = request?.headers?.accept ?? 'application/json'
+  if (contentType === 'application/json') {
+    return response.json(context.response)
+  }
+
+  return response.send(context.response)
+}

package/src/handlers/unauthorized.js

@@ -0,0 +1,8 @@
+export const unauthorized = async (context, request, response) => {
+  response.status(401)
+  return {
+    status: 401,
+    timestamp: new Date(),
+    message: 'Unauthorized'
+  }
+}

package/src/openapi.js

@@ -0,0 +1,15 @@
+import { readFile } from 'node:fs/promises'
+
+/**
+ * Get the OpenAPI specification from the file.
+ * @async
+ * @param {object} params
+ * @param {string} params.file
+ * @param {string=} params.base
+ * @returns {Promise<{ openAPISpecification: object; }>}
+ */
+export const openAPI = async ({ file, base = import.meta.url }) => {
+  const fileUrl = new URL(file, base)
+  const openAPISpecification = JSON.parse(await readFile(fileUrl, 'utf8'))
+  return { openAPISpecification }
+}

package/src/operation-ids.js

@@ -0,0 +1,14 @@
+const operations = ['get', 'put', 'patch', 'post', 'delete']
+
+/**
+ * Get all operation ID's from the specification.
+ * @param {object} params
+ * @param {object} params.specification
+ * @returns {string[]}
+ */
+export const operationIds = ({ specification }) => Object.values(specification.paths)
+  .map((path) => Object.entries(path)
+    .map(([operation, data]) => operations.includes(operation)
+      ? data.operationId
+      : null))
+  .flat()

package/src/params.js

@@ -0,0 +1,34 @@
+import { types } from './types.js'
+
+/**
+ * Parse params to the types defined in the spec
+ * @param {object} params
+ * @param {object} params.query
+ * @param {object} params.spec
+ * @returns {object}
+ */
+export const parseParams = ({ query, spec }) =>
+  spec.map(parameter => {
+    const { name, schema } = parameter
+    const { type, default: defaultValue, example: exampleValue } = schema
+    const Type = types[type]
+    const paramName = query?.[name]
+
+    if (!paramName) {
+      return { name, value: defaultValue ?? exampleValue }
+    }
+
+    if (Type === Boolean) {
+      return {
+        name,
+        value: JSON.parse(paramName.toLowerCase())
+      }
+    }
+
+    const value = new Type(paramName).valueOf()
+    return { name, value }
+  })
+    .reduce((acc, { name, value }) => {
+      acc[name] = value
+      return acc
+    }, {})

package/src/router.js

@@ -0,0 +1,79 @@
+import { OpenAPIBackend } from 'openapi-backend'
+import addFormats from 'ajv-formats'
+import { makeExpressCallback } from './express-callback.js'
+import { operationIds } from './operation-ids.js'
+import { notFound } from './handlers/not-found.js'
+import { requestValidation } from './handlers/request-validation.js'
+import { responseValidation } from './handlers/response-validation.js'
+import { unauthorized } from './handlers/unauthorized.js'
+
+/**
+ * @typedef {import('./api.js').Logger} Logger
+ * @typedef {import('./api.js').SecurityHandler} SecurityHandler
+ * Setup the router
+ * @param {object} params
+ * @param {string=} params.secret
+ * @param {object} params.openAPISpecification
+ * @param {object} params.controllers
+ * @param {string=} params.apiRoot
+ * @param {boolean=} params.strictSpecification
+ * @param {boolean=} params.errorDetails
+ * @param {Logger=} params.logger
+ * @param {object=} params.meta
+ * @param {SecurityHandler[]=} params.securityHandlers
+ * @returns {{ api, openAPISpecification: object }}
+ */
+export const setupRouter = ({ secret, openAPISpecification, controllers, apiRoot, strictSpecification, errorDetails, logger, meta, securityHandlers = [] }) => {
+  const api = new OpenAPIBackend({
+    definition: openAPISpecification,
+    apiRoot,
+    strict: strictSpecification,
+    customizeAjv: (originalAjv) => {
+      addFormats(originalAjv)
+      return originalAjv
+    }
+  })
+
+  api.register({
+    unauthorizedHandler: unauthorized,
+    validationFail: requestValidation,
+    notFound,
+    postResponseHandler: responseValidation
+  })
+
+  operationIds({ specification: openAPISpecification }).forEach((operationId) => {
+    if (!Object.hasOwn(controllers, operationId)) {
+      return
+    }
+    api.register(
+      operationId,
+      makeExpressCallback({
+        controller: controllers[operationId],
+        specification: openAPISpecification,
+        errorDetails,
+        logger,
+        meta
+      })
+    )
+  })
+
+  api.register('notImplemented', (context, request, response) => {
+    const { mock } = context.api.mockResponseForOperation(
+      context.operation.operationId
+    )
+    return mock
+  })
+
+  if (secret) {
+    api.registerSecurityHandler(
+      'apiKey',
+      (context) => context.request.headers['x-api-key'] === secret
+    )
+  }
+
+  securityHandlers.forEach((securityHandler) => {
+    api.registerSecurityHandler(securityHandler.name, securityHandler.handler)
+  })
+
+  return { api, openAPISpecification }
+}

package/src/server.js

@@ -0,0 +1,111 @@
+import express from 'express'
+import cors from 'cors'
+import compression from 'compression'
+import helmet from 'helmet'
+import * as Sentry from '@sentry/node'
+import bodyParser from 'body-parser'
+import { openAPI } from './openapi.js'
+import { Api } from './api.js'
+
+/**
+ * Get the origin resource policy
+ * @param {string} origin
+ * @returns {{ crossOriginResourcePolicy: { policy: string, directives: object } }}
+ */
+const getOriginResourcePolicy = (origin) => ({
+  crossOriginResourcePolicy: {
+    policy: origin === '*' ? 'cross-origin' : 'same-origin',
+    directives: {
+      // ...
+      'require-trusted-types-for': ["'script'"]
+    }
+  }
+})
+
+/**
+ * @typedef {import('express-serve-static-core').Request} Request
+ * @typedef {import('express-serve-static-core').Response} Response
+ * @typedef {import('openapi-backend').Context} Context
+ * @typedef {import('./api.js').ApiSchema} ApiSchema
+ * @typedef {import('./api.js').Logger} Logger
+ * @typedef {import('express').Express} Express
+ * @typedef {object} Controller
+ * @property {Context=} context
+ * @property {Request=} request
+ * @property {Response=} response
+ * @property {object=} parameters
+ * @property {object=} specification
+ * @property {object=} post
+ * @property {string=} url
+ * @property {Logger=} logger
+ * @property {object=} meta
+ * @typedef {object} SentryConfig
+ * @property {string=} dsn
+ * @property {number=} tracesSampleRate
+ * @property {number=} profilesSampleRate
+ * @property {string=} release
+ */
+
+/**
+ * Setup the server
+ * @async
+ * @param {object} params
+ * @param {ApiSchema[]} params.apis
+ * @param {string=} params.origin
+ * @param {string=} params.staticFolder
+ * @param {SentryConfig=} params.sentry
+ * @param {string=} params.poweredBy
+ * @param {string=} params.version
+ * @returns {Promise<{ app: Express }>}
+ */
+export const setupServer = async ({ apis, origin = '*', staticFolder, sentry, poweredBy = 'TroJS', version = '1.0.0' }) => {
+  const corsOptions = {
+    origin
+  }
+
+  const app = express()
+
+  if (sentry) {
+    Sentry.init({
+      dsn: sentry.dsn,
+      integrations: [
+        new Sentry.Integrations.Http({ tracing: true }),
+        new Sentry.Integrations.Express({ app })
+      ],
+      tracesSampleRate: sentry.tracesSampleRate || 1.0,
+      profilesSampleRate: sentry.profilesSampleRate || 1.0,
+      release: sentry.release
+    })
+
+    app.use(Sentry.Handlers.requestHandler())
+  }
+
+  app.use(cors(corsOptions))
+  app.use(compression())
+  app.use(helmet(getOriginResourcePolicy(origin)))
+  app.use(express.json())
+  app.use(bodyParser.urlencoded({ extended: false }))
+  app.use((_request, response, next) => {
+    response.setHeader('X-Powered-By', poweredBy)
+    response.setHeader('X-Version', version)
+    next()
+  })
+
+  if (staticFolder) {
+    app.use(express.static(staticFolder))
+  }
+
+  apis.forEach((api) => {
+    const apiRoutes = new Api(api)
+    const routes = apiRoutes.setup()
+    app.use(`/${api.version}`, routes)
+  })
+
+  if (sentry) {
+    app.use(Sentry.Handlers.errorHandler())
+  }
+
+  return { app }
+}
+
+export { openAPI, Api }

package/src/types.js

@@ -0,0 +1,12 @@
+const types = {
+  string: String,
+  array: Array,
+  object: Object,
+  number: Number,
+  integer: Number,
+  boolean: Boolean,
+  url: URL,
+  date: Date
+}
+
+export { types }