Add express-openapi types

erikjuhani · erikjuhani · commit 901346dffc5e · 2024-09-06T23:55:35.000+03:00
This commit includes typing all the public facing signatures. The types also include API documentation in JSDoc format that is available in the root README of the repository. Most of the types were deduced by hand from the source code and tested with actual runtime data to make sure that the written types match with the runtime data. The component methods use function overloading to provide better code completion of the expected parameters and return values. For example giving a type and a name to `component("examples", "FooExample")` returns the expected type of `ReferenceObject` conforming to the API documentation. Similarly setting the type for the component function affects what it will return or take as an input. The input parameter and return type will conform to the expected type. For example: ```ts const schemas = openapi.component("schemas"); // ^? { [key: string]: SchemaObject | ReferenceObject } const examples = openapi.component("examples"); // ^? { [key: string]: ExampleObject | ReferenceObject } ``` The types utilize existing types defined in "openapi-types" and most of the public facing API functions rely on these types. The initial typings file was derived from the work presented here: #25 (comment)
diff --git a/index.d.ts b/index.d.ts
@@ -0,0 +1,252 @@
+import type { IRouter, Request, RequestHandler as Middleware, Response, NextFunction } from "express";
+import type { OpenAPIV3 } from "openapi-types";
+import type { SwaggerUIOptions } from "swagger-ui";
+
+type Options = {
+  basePath?: string;
+  htmlui?: "swagger-ui";
+  coerce?: "true" | "false";
+};
+
+interface OpenApiMiddleware extends Middleware {
+  document: OpenAPIV3.Document;
+  options: Options;
+  routePrefix: string;
+  generateDocument: (doc: OpenAPIV3.Document, router?: IRouter, basePath?: string) => OpenAPIV3.Document;
+  /**
+   * Registers a path with the OpenAPI document.
+   * The path `definition` is an {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject OperationObject}
+   * with all of the information about the requests and responses on that route.
+   *
+   * It returns a middleware function which can be used in an express app.
+   *
+   * @example
+   *
+   * ```ts
+   * app.get('/:foo', oapi.path({
+   *   description: 'Get a foo',
+   *   responses: {
+   *     200: {
+   *       content: {
+   *         'application/json': {
+   *           schema: {
+   *             type: 'object',
+   *             properties: {
+   *               foo: { type: 'string' }
+   *             }
+   *           }
+   *         }
+   *       }
+   *     }
+   *   }
+   * }), (req, res) => {
+   *  res.json({
+   *    foo: req.params.foo
+   *  })
+   * })
+   * ```
+   */
+  path: (schema?: OpenAPIV3.OperationObject) => Middleware;
+  /**
+   * Registers a path with the OpenAPI document, also ensures incoming requests are valid against the schema.
+   * The path `definition` is an {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject OperationObject}
+   * with all of the information about the requests and responses on that route.
+   *
+   * It returns a middleware function which can be used in an express app and will call `next(err)` if the incoming request is invalid.
+   * The error is created with ({@link https://www.npmjs.com/package/http-errors http-errors}), and then is augmented with information about the schema and validation errors.
+   * Validation uses ({@link https://www.npmjs.com/package/ajv ajv}), and `err.validationErrors` is the format exposed by that package.
+   *
+   * Pass `{ keywords: [] }` as `pathOpts` to support custom validation based on ajv-keywords.
+   *
+   * @example
+   * ```js
+   * app.get('/:foo', oapi.validPath({
+   *   description: 'Get a foo',
+   *   responses: {
+   *     200: {
+   *       content: {
+   *         'application/json': {
+   *           schema: {
+   *             type: 'object',
+   *             properties: {
+   *               foo: { type: 'string' }
+   *             }
+   *           }
+   *         }
+   *       }
+   *     },
+   *     400: {
+   *       content: {
+   *         'application/json': {
+   *           schema: {
+   *             type: 'object',
+   *             properties: {
+   *               error: { type: 'string' }
+   *             }
+   *           }
+   *         }
+   *       }
+   *     }
+   *   }
+   * }), (err, req, res, next) => {
+   *   res.status(err.status).json({
+   *     error: err.message,
+   *     validation: err.validationErrors,
+   *     schema: err.validationSchema
+   *   })
+   * })
+   *
+   * app.get('/zoom', oapi.validPath({
+   *   ...
+   *   requestBody: {
+   *     required: true,
+   *     content: {
+   *       'application/json': {
+   *         schema: {
+   *           type: 'object',
+   *           properties: {
+   *             name: { type: 'string', not: { regexp: '/^[A-Z]/' } }
+   *           }
+   *         }
+   *       }
+   *     }
+   *   },
+   *   ...
+   * }, { keywords: ['regexp'] }), (err, req, res, next) => {
+   *   res.status(err.status).json({
+   *     error: err.message,
+   *     validation: err.validationErrors,
+   *     schema: err.validationSchema
+   *   })
+   * })
+   * ```
+   */
+  validPath: (schema?: OpenAPIV3.OperationObject, pathOpts?: { strict?: boolan; keywords?: string | string[] }) => Middleware;
+  /**
+   * Defines a new {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#components-object Component} on the document.
+   *
+   * @example
+   * ```js
+   * oapi.component('examples', 'FooExample', {
+   *   summary: 'An example of foo',
+   *   value: 'bar'
+   * })
+   * ```
+   *
+   * If `name` is defined but `definition` is not, it will return a {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#referenceObject Reference Object} pointing to the component by that name.
+   *
+   * @example
+   * ```js
+   * oapi.component('examples', 'FooExample')
+   * // { '$ref': '#/components/examples/FooExample' }
+   * ```
+   *
+   * If neither `definition` nor `name` are passed, the function will return the full `components` json.
+   *
+   * @example
+   * ```js
+   * oapi.component('examples')
+   * // { summary: 'An example of foo', value: 'bar' }
+   * ```
+   */
+  component: {
+    <Type extends keyof Component>(type: Type): OpenAPIV3.ComponentsObject[Type];
+    <Type extends keyof Component>(type: Type, name: string): OpenAPIV3.ReferenceObject;
+    <Type extends keyof Component>(type: Type, name: string, definition: Component[Type]): OpenApiMiddleware;
+  };
+  schema: {
+    (name: string): OpenAPIV3.ReferenceObject;
+    (name: string, definition: OpenAPIV3.SchemaObject): OpenApiMiddleware;
+  };
+  response: {
+    (name: string): OpenAPIV3.ReferenceObject;
+    (name: string, definition: OpenAPIV3.ResponseObject): OpenApiMiddleware;
+  };
+  parameters: {
+    (name: string): OpenAPIV3.ReferenceObject;
+    (name: string, definition: OpenAPIV3.ParameterObject): OpenApiMiddleware;
+  };
+  examples: {
+    (name: string): OpenAPIV3.ReferenceObject;
+    (name: string, definition: OpenAPIV3.ExampleObject): OpenApiMiddleware;
+  };
+  requestBodies: {
+    (name: string): OpenAPIV3.ReferenceObject;
+    (name: string, definition: OpenAPIV3.RequestBodyObject): OpenApiMiddleware;
+  };
+  headers: {
+    (name: string): OpenAPIV3.ReferenceObject;
+    (name: string, definition: OpenAPIV3.HeaderObject): OpenApiMiddleware;
+  };
+  securitySchemes: {
+    (name: string): OpenAPIV3.ReferenceObject;
+    (name: string, definition: OpenAPIV3.SecuritySchemeObject): OpenApiMiddleware;
+  };
+  links: {
+    (name: string): OpenAPIV3.ReferenceObject;
+    (name: string, definition: OpenAPIV3.LinkObject): OpenApiMiddleware;
+  };
+  callbacks: {
+    (name: string): OpenAPIV3.ReferenceObject;
+    (name: string, definition: OpenAPIV3.CallbackObject): OpenApiMiddleware;
+  };
+  /**
+   * Serve an interactive UI for exploring the OpenAPI document.
+   *
+   * {@link https://www.npmjs.com/package/swagger-ui SwaggerUI} is one of the most popular tools for viewing OpenAPI documents and are bundled with the middleware.
+   * The UI is not turned on by default but can be with the option mentioned above or by using one of these middleware.
+   * Both interactive UIs also accept an optional object as a function argument which accepts configuration parameters for Swagger and Redoc.
+   * The full list of Swagger and Redoc configuration options can be found {@link https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/ here} 
+   * and {@link https://redocly.com/docs/redoc/config/ here} respectively.
+   *
+   * @example
+   * ```js
+   * app.use('/swaggerui', oapi.swaggerui())
+   * ```
+   */
+  swaggerui: (options?: SwaggerUIOptions) => Middleware[];
+}
+
+/** 
+ * Utility type helper to return value types from the given Record type `T`.
+ */
+type ObjectValue<T extends Record<string, unknown>> = T extends { [key: string]: infer V } ? V : never;
+
+/**
+ * Utility type helper to compose a map of `OpenAPIV3.ComponentsObject`.
+ *
+ * This map type is used to determine what type we are allowed to input or
+ * expected to return from the {@link OpenApiMiddleware.component} function.
+ */
+type Component = {
+  [K in keyof OpenAPIV3.ComponentsObject]-?: ObjectValue<OpenAPIV3.ComponentsObject[K]>;
+};
+
+/**
+ * Creates an instance of the documentation middleware.
+ * The function that is returned is a middleware function decorated with helper methods for setting up the api documentation.
+ *
+ * @param route - A route for which the documentation will be served at
+ * @param doc - Base document on top of which the paths will be added
+ * @param options - Options
+ * @param options.coerce - Enable data type {@link https://www.npmjs.com/package/ajv#coercing-data-types coercion}
+ * @param options.htmlui - Turn on serving `swagger-ui` html ui
+ * @param options.basePath - When set, will strip the value of `basePath` from the start of every path
+ *
+ * Coerce 
+ *
+ * By default `coerceTypes` is set to `true` for `ajv`, but a copy of the `req` data is passed to prevent modifying the `req` in an unexpected way.
+ * This is because the `coerceTypes` option in ({@link https://github.com/ajv-validator/ajv/issues/549 `ajv` modifies the input}).
+ * If this is the behavior you want, you can pass `true` for this and a copy will not be made.
+ * This will result in params in the path or query with type `number` will be converted to numbers {@link https://github.com/epoberezkin/ajv/blob/master/COERCION.md based on the rules from `ajv`}.
+ */
+function openapi(): OpenApiMiddleware;
+function openapi(doc: OpenAPIV3.Document, opts?: Options): OpenApiMiddleware;
+function openapi(route: string, doc?: OpenAPIV3.Document, opts?: Options): OpenApiMiddleware;
+
+namespace openapi {
+  const minimumViableDocument: OpenAPIV3.Document;
+  const defaultRoutePrefix: "/openapi";
+}
+
+export = openapi;
diff --git a/package.json b/package.json
@@ -11,6 +11,7 @@
   ],
   "license": "ISC",
   "main": "index.js",
+  "types": "index.d.ts",
   "repository": {
     "type": "git",
     "url": "wesleytodd/express-openapi"
@@ -21,10 +22,13 @@
     "postpublish": "git push origin && git push origin --tags"
   },
   "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/swagger-ui": "^3.52.4",
     "express": "^4.18.2",
     "express4": "github:expressjs/express#4.19.2",
     "express5": "npm:express@^5.0.0-beta.3",
     "mocha": "^10.3.0",
+    "openapi-types": "^12.1.3",
     "standard": "^17.1.0",
     "supertest": "^6.3.4"
   },
diff --git a/tsconfig.json b/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "es2016",
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true
+  }
+}
