feat: add OpenAPI validation to a few endpoints (#1409)

* feat: add OpenAPI validation to a few endpoints (2)

* refactor: use package version as the OpenAPI version

* refactor: keep the existing OpenAPI page for now

* refactor: add snapshots tests for the OpenAPI output

* refactor: validate Content-Type by default

* refactor: update vulnerable deps

* refactor: fix documentation URL to match schema

* refactor: improve external type declaration

* refactor: remove unused package resolutions

* refactor: try express-openapi fork

* Update package.json

* Update src/lib/services/openapi-service.ts

* Update src/lib/types/openapi.d.ts

* Update src/lib/types/openapi.d.ts

Co-authored-by: Ivar Conradi Østhus <ivarconr@gmail.com>

package.json

@@ -98,6 +98,7 @@
     "joi": "^17.3.0",
     "js-yaml": "^4.1.0",
     "knex": "1.0.4",
+    "json-schema-to-ts": "^1.6.5",
     "log4js": "^6.0.0",
     "memoizee": "^0.4.15",
     "mime": "^2.4.2",
@@ -105,6 +106,7 @@
     "mustache": "^4.1.0",
     "node-fetch": "^2.6.7",
     "nodemailer": "^6.5.0",
+    "openapi-types": "^10.0.0",
     "owasp-password-strength-test": "^1.3.0",
     "parse-database-url": "^0.3.0",
     "pg": "^8.7.3",
@@ -115,6 +117,7 @@
     "serve-favicon": "^2.5.0",
     "stoppable": "^1.1.0",
     "type-is": "^1.6.18",
+    "@unleash/express-openapi": "^0.2.0",
     "unleash-frontend": "4.10.0-beta.6",
     "uuid": "^8.3.2",
     "semver": "^7.3.5"

src/lib/app.ts

@@ -69,6 +69,11 @@ export default async function getApp(
     if (config.enableOAS) {
         app.use(`${baseUriPath}/oas`, express.static('docs/api/oas'));
     }
+
+    if (config.enableOAS && services.openApiService) {
+        services.openApiService.useDocs(app);
+    }
+
     switch (config.authentication.type) {
         case IAuthType.OPEN_SOURCE: {
             app.use(baseUriPath, apiTokenMiddleware(config, services));
@@ -128,6 +133,10 @@ export default async function getApp(
     // Setup API routes
     app.use(`${baseUriPath}/`, new IndexRouter(config, services).router);
 
+    if (services.openApiService) {
+        services.openApiService.useErrorHandler(app);
+    }
+
     if (process.env.NODE_ENV !== 'production') {
         app.use(errorHandler());
     }
@@ -144,5 +153,6 @@ export default async function getApp(
 
         res.send(indexHTML);
     });
+
     return app;
 }

src/lib/openapi/index.ts

@@ -0,0 +1,45 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { featuresSchema } from './spec/features-schema';
+import { featureSchema } from './spec/feature-schema';
+import { strategySchema } from './spec/strategy-schema';
+import { variantSchema } from './spec/variant-schema';
+import { overrideSchema } from './spec/override-schema';
+import { createFeatureSchema } from './spec/create-feature-schema';
+import { constraintSchema } from './spec/constraint-schema';
+
+// Create the base OpenAPI schema, with everything except paths.
+export const createOpenApiSchema = (
+    serverUrl?: string,
+): Omit<OpenAPIV3.Document, 'paths'> => {
+    return {
+        openapi: '3.0.3',
+        servers: serverUrl ? [{ url: serverUrl }] : [],
+        info: {
+            title: 'Unleash API',
+            version: process.env.npm_package_version,
+        },
+        security: [
+            {
+                apiKey: [],
+            },
+        ],
+        components: {
+            securitySchemes: {
+                apiKey: {
+                    type: 'apiKey',
+                    in: 'header',
+                    name: 'Authorization',
+                },
+            },
+            schemas: {
+                createFeatureSchema,
+                featuresSchema,
+                featureSchema,
+                strategySchema,
+                variantSchema,
+                overrideSchema,
+                constraintSchema,
+            },
+        },
+    };
+};

src/lib/openapi/spec/constraint-schema.ts

@@ -0,0 +1,24 @@
+import { createSchemaObject, CreateSchemaType } from '../types';
+
+export const schema = {
+    type: 'object',
+    required: ['contextName', 'operator'],
+    properties: {
+        contextName: {
+            type: 'string',
+        },
+        operator: {
+            type: 'string',
+        },
+        values: {
+            type: 'array',
+            items: {
+                type: 'string',
+            },
+        },
+    },
+} as const;
+
+export type ConstraintSchema = CreateSchemaType<typeof schema>;
+
+export const constraintSchema = createSchemaObject(schema);

src/lib/openapi/spec/create-feature-request.ts

@@ -0,0 +1,12 @@
+import { OpenAPIV3 } from 'openapi-types';
+
+export const createFeatureRequest: OpenAPIV3.RequestBodyObject = {
+    required: true,
+    content: {
+        'application/json': {
+            schema: {
+                $ref: '#/components/schemas/createFeatureSchema',
+            },
+        },
+    },
+};

src/lib/openapi/spec/create-feature-schema.ts

@@ -0,0 +1,24 @@
+import { createSchemaObject, CreateSchemaType } from '../types';
+
+const schema = {
+    type: 'object',
+    required: ['name'],
+    properties: {
+        name: {
+            type: 'string',
+        },
+        type: {
+            type: 'string',
+        },
+        description: {
+            type: 'string',
+        },
+        impressionData: {
+            type: 'boolean',
+        },
+    },
+} as const;
+
+export type CreateFeatureSchema = CreateSchemaType<typeof schema>;
+
+export const createFeatureSchema = createSchemaObject(schema);

src/lib/openapi/spec/feature-response.ts

@@ -0,0 +1,12 @@
+import { OpenAPIV3 } from 'openapi-types';
+
+export const featureResponse: OpenAPIV3.ResponseObject = {
+    description: 'featureResponse',
+    content: {
+        'application/json': {
+            schema: {
+                $ref: '#/components/schemas/featureSchema',
+            },
+        },
+    },
+};

src/lib/openapi/spec/feature-schema.ts

@@ -0,0 +1,55 @@
+import { createSchemaObject, CreateSchemaType } from '../types';
+
+const schema = {
+    type: 'object',
+    required: ['name', 'project'],
+    properties: {
+        name: {
+            type: 'string',
+        },
+        type: {
+            type: 'string',
+        },
+        description: {
+            type: 'string',
+        },
+        project: {
+            type: 'string',
+        },
+        enabled: {
+            type: 'boolean',
+        },
+        stale: {
+            type: 'boolean',
+        },
+        impressionData: {
+            type: 'boolean',
+        },
+        createdAt: {
+            type: 'string',
+            format: 'date',
+            nullable: true,
+        },
+        lastSeenAt: {
+            type: 'string',
+            format: 'date',
+            nullable: true,
+        },
+        strategies: {
+            type: 'array',
+            items: {
+                $ref: '#/components/schemas/strategySchema',
+            },
+        },
+        variants: {
+            items: {
+                $ref: '#/components/schemas/variantSchema',
+            },
+            type: 'array',
+        },
+    },
+} as const;
+
+export type FeatureSchema = CreateSchemaType<typeof schema>;
+
+export const featureSchema = createSchemaObject(schema);

src/lib/openapi/spec/features-response.ts

@@ -0,0 +1,12 @@
+import { OpenAPIV3 } from 'openapi-types';
+
+export const featuresResponse: OpenAPIV3.ResponseObject = {
+    description: 'featuresResponse',
+    content: {
+        'application/json': {
+            schema: {
+                $ref: '#/components/schemas/featuresSchema',
+            },
+        },
+    },
+};

src/lib/openapi/spec/features-schema.ts

@@ -0,0 +1,21 @@
+import { createSchemaObject, CreateSchemaType } from '../types';
+
+export const schema = {
+    type: 'object',
+    required: ['version', 'features'],
+    properties: {
+        version: {
+            type: 'integer',
+        },
+        features: {
+            type: 'array',
+            items: {
+                $ref: '#/components/schemas/featureSchema',
+            },
+        },
+    },
+} as const;
+
+export type FeaturesSchema = CreateSchemaType<typeof schema>;
+
+export const featuresSchema = createSchemaObject(schema);

src/lib/openapi/spec/override-schema.ts

@@ -0,0 +1,21 @@
+import { createSchemaObject, CreateSchemaType } from '../types';
+
+export const schema = {
+    type: 'object',
+    required: ['contextName', 'values'],
+    properties: {
+        contextName: {
+            type: 'string',
+        },
+        values: {
+            type: 'array',
+            items: {
+                type: 'string',
+            },
+        },
+    },
+} as const;
+
+export type OverrideSchema = CreateSchemaType<typeof schema>;
+
+export const overrideSchema = createSchemaObject(schema);

src/lib/openapi/spec/strategy-schema.ts

@@ -0,0 +1,27 @@
+import { createSchemaObject, CreateSchemaType } from '../types';
+
+export const schema = {
+    type: 'object',
+    required: ['id', 'name', 'constraints', 'parameters'],
+    properties: {
+        id: {
+            type: 'string',
+        },
+        name: {
+            type: 'string',
+        },
+        constraints: {
+            type: 'array',
+            items: {
+                $ref: '#/components/schemas/constraintSchema',
+            },
+        },
+        parameters: {
+            type: 'object',
+        },
+    },
+} as const;
+
+export type StrategySchema = CreateSchemaType<typeof schema>;
+
+export const strategySchema = createSchemaObject(schema);

src/lib/openapi/spec/variant-schema.ts

@@ -0,0 +1,33 @@
+import { createSchemaObject, CreateSchemaType } from '../types';
+
+export const schema = {
+    type: 'object',
+    required: ['name', 'weight', 'weightType', 'stickiness', 'overrides'],
+    properties: {
+        name: {
+            type: 'string',
+        },
+        weight: {
+            type: 'number',
+        },
+        weightType: {
+            type: 'string',
+        },
+        stickiness: {
+            type: 'string',
+        },
+        payload: {
+            type: 'object',
+        },
+        overrides: {
+            type: 'array',
+            items: {
+                $ref: '#/components/schemas/overrideSchema',
+            },
+        },
+    },
+} as const;
+
+export type VariantSchema = CreateSchemaType<typeof schema>;
+
+export const variantSchema = createSchemaObject(schema);

src/lib/openapi/types.ts

@@ -0,0 +1,21 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { FromSchema } from 'json-schema-to-ts';
+import { DeepMutable } from '../types/mutable';
+
+// Admin paths must have the "admin" tag.
+export interface AdminApiOperation
+    extends Omit<OpenAPIV3.OperationObject, 'tags'> {
+    tags: ['admin'];
+}
+
+// Client paths must have the "client" tag.
+export interface ClientApiOperation
+    extends Omit<OpenAPIV3.OperationObject, 'tags'> {
+    tags: ['client'];
+}
+
+// Create a type from a const schema object.
+export type CreateSchemaType<T> = FromSchema<T>;
+
+// Create an OpenAPIV3.SchemaObject from a const schema object.
+export const createSchemaObject = <T>(schema: T): DeepMutable<T> => schema;

src/lib/routes/admin-api/archive.ts

@@ -1,4 +1,4 @@
-import { Response } from 'express';
+import { Request, Response } from 'express';
 import { IUnleashConfig } from '../../types/option';
 import { IUnleashServices } from '../../types/services';
 import { Logger } from '../../logger';
@@ -9,6 +9,8 @@ import { extractUsername } from '../../util/extract-user';
 import { DELETE_FEATURE, UPDATE_FEATURE } from '../../types/permissions';
 import FeatureToggleService from '../../services/feature-toggle-service';
 import { IAuthRequest } from '../unleash-types';
+import { featuresResponse } from '../../openapi/spec/features-response';
+import { FeaturesSchema } from '../../openapi/spec/features-schema';
 
 export default class ArchiveController extends Controller {
     private readonly logger: Logger;
@@ -19,13 +21,27 @@ export default class ArchiveController extends Controller {
         config: IUnleashConfig,
         {
             featureToggleServiceV2,
-        }: Pick<IUnleashServices, 'featureToggleServiceV2'>,
+            openApiService,
+        }: Pick<IUnleashServices, 'featureToggleServiceV2' | 'openApiService'>,
     ) {
         super(config);
         this.logger = config.getLogger('/admin-api/archive.js');
         this.featureService = featureToggleServiceV2;
 
-        this.get('/features', this.getArchivedFeatures);
+        this.route({
+            method: 'get',
+            path: '/features',
+            acceptAnyContentType: true,
+            handler: this.getArchivedFeatures,
+            middleware: [
+                openApiService.validPath({
+                    tags: ['admin'],
+                    responses: { 200: featuresResponse },
+                    deprecated: true,
+                }),
+            ],
+        });
+
         this.delete('/:featureName', this.deleteFeature, DELETE_FEATURE);
         this.post(
             '/revive/:featureName',
@@ -35,7 +51,10 @@ export default class ArchiveController extends Controller {
     }
 
     // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
-    async getArchivedFeatures(req, res): Promise<void> {
+    async getArchivedFeatures(
+        req: Request,
+        res: Response<FeaturesSchema>,
+    ): Promise<void> {
         const features = await this.featureService.getMetadataForAllFeatures(
             true,
         );

src/lib/routes/admin-api/feature.ts

@@ -18,6 +18,8 @@ import { IFeatureToggleQuery } from '../../types/model';
 import FeatureTagService from '../../services/feature-tag-service';
 import { IAuthRequest } from '../unleash-types';
 import { DEFAULT_ENV } from '../../util/constants';
+import { featuresResponse } from '../../openapi/spec/features-response';
+import { FeaturesSchema } from '../../openapi/spec/features-schema';
 
 const version = 1;
 
@@ -31,9 +33,10 @@ class FeatureController extends Controller {
         {
             featureTagService,
             featureToggleServiceV2,
+            openApiService,
         }: Pick<
             IUnleashServices,
-            'featureTagService' | 'featureToggleServiceV2'
+            'featureTagService' | 'featureToggleServiceV2' | 'openApiService'
         >,
     ) {
         super(config);
@@ -57,7 +60,20 @@ class FeatureController extends Controller {
             this.post('/:featureName/stale/off', this.staleOff, UPDATE_FEATURE);
         }
 
-        this.get('/', this.getAllToggles);
+        this.route({
+            method: 'get',
+            path: '/',
+            acceptAnyContentType: true,
+            handler: this.getAllToggles,
+            middleware: [
+                openApiService.validPath({
+                    tags: ['admin'],
+                    responses: { 200: featuresResponse },
+                    deprecated: true,
+                }),
+            ],
+        });
+
         this.post('/validate', this.validate, NONE);
         this.get('/:featureName/tags', this.listTags);
         this.post('/:featureName/tags', this.addTag, UPDATE_FEATURE);
@@ -97,7 +113,10 @@ class FeatureController extends Controller {
         return query;
     }
 
-    async getAllToggles(req: Request, res: Response): Promise<void> {
+    async getAllToggles(
+        req: Request,
+        res: Response<FeaturesSchema>,
+    ): Promise<void> {
         const query = await this.prepQuery(req.query);
         const features = await this.service.getFeatureToggles(query);
 

src/lib/routes/admin-api/project/features.ts

@@ -21,6 +21,12 @@ import {
 } from '../../../types/model';
 import { extractUsername } from '../../../util/extract-user';
 import { IAuthRequest } from '../../unleash-types';
+import { createFeatureRequest } from '../../../openapi/spec/create-feature-request';
+import { featureResponse } from '../../../openapi/spec/feature-response';
+import { CreateFeatureSchema } from '../../../openapi/spec/create-feature-schema';
+import { FeatureSchema } from '../../../openapi/spec/feature-schema';
+import { serializeDates } from '../../../util/serialize-dates';
+import { featuresResponse } from '../../../openapi/spec/features-response';
 
 interface FeatureStrategyParams {
     projectId: string;
@@ -56,7 +62,7 @@ const PATH_STRATEGY = `${PATH_STRATEGIES}/:strategyId`;
 
 type ProjectFeaturesServices = Pick<
     IUnleashServices,
-    'featureToggleServiceV2' | 'projectHealthService'
+    'featureToggleServiceV2' | 'projectHealthService' | 'openApiService'
 >;
 
 export default class ProjectFeaturesController extends Controller {
@@ -66,7 +72,7 @@ export default class ProjectFeaturesController extends Controller {
 
     constructor(
         config: IUnleashConfig,
-        { featureToggleServiceV2 }: ProjectFeaturesServices,
+        { featureToggleServiceV2, openApiService }: ProjectFeaturesServices,
     ) {
         super(config);
         this.featureService = featureToggleServiceV2;
@@ -107,10 +113,48 @@ export default class ProjectFeaturesController extends Controller {
             DELETE_FEATURE_STRATEGY,
         );
 
-        this.get(PATH, this.getFeatures);
-        this.post(PATH, this.createFeature, CREATE_FEATURE);
+        this.route({
+            method: 'get',
+            path: PATH,
+            acceptAnyContentType: true,
+            handler: this.getFeatures,
+            middleware: [
+                openApiService.validPath({
+                    tags: ['admin'],
+                    responses: { 200: featuresResponse },
+                }),
+            ],
+        });
+
         this.post(PATH_FEATURE_CLONE, this.cloneFeature, CREATE_FEATURE);
-        this.get(PATH_FEATURE, this.getFeature);
+
+        this.route({
+            method: 'post',
+            path: PATH,
+            handler: this.createFeature,
+            permission: CREATE_FEATURE,
+            middleware: [
+                openApiService.validPath({
+                    tags: ['admin'],
+                    requestBody: createFeatureRequest,
+                    responses: { 200: featureResponse },
+                }),
+            ],
+        });
+
+        this.route({
+            method: 'get',
+            path: PATH_FEATURE,
+            acceptAnyContentType: true,
+            handler: this.getFeature,
+            middleware: [
+                openApiService.validPath({
+                    tags: ['admin'],
+                    responses: { 200: featureResponse },
+                }),
+            ],
+        });
+
         this.put(PATH_FEATURE, this.updateFeature, UPDATE_FEATURE);
         this.patch(PATH_FEATURE, this.patchFeature, UPDATE_FEATURE);
         this.delete(PATH_FEATURE, this.archiveFeature, DELETE_FEATURE);
@@ -150,17 +194,19 @@ export default class ProjectFeaturesController extends Controller {
     }
 
     async createFeature(
-        req: IAuthRequest<FeatureParams, any, FeatureToggleDTO, any>,
-        res: Response,
+        req: IAuthRequest<FeatureParams, FeatureSchema, CreateFeatureSchema>,
+        res: Response<FeatureSchema>,
     ): Promise<void> {
         const { projectId } = req.params;
+
         const userName = extractUsername(req);
         const created = await this.featureService.createFeatureToggle(
             projectId,
             req.body,
             userName,
         );
-        res.status(201).json(created);
+
+        res.status(201).json(serializeDates(created));
     }
 
     async getFeature(

src/lib/routes/controller.ts

@@ -1,4 +1,4 @@
-import { IRouter, Router, Request, Response } from 'express';
+import { IRouter, Router, Request, Response, RequestHandler } from 'express';
 import { Logger } from 'lib/logger';
 import { IUnleashConfig } from '../types/option';
 import { NONE } from '../types/permissions';
@@ -18,6 +18,16 @@ interface IRequestHandler<
     ): Promise<void> | void;
 }
 
+interface IRouteOptions {
+    method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    path: string;
+    permission?: string;
+    middleware?: RequestHandler[];
+    handler: IRequestHandler;
+    acceptAnyContentType?: boolean;
+    acceptedContentTypes?: string[];
+}
+
 const checkPermission = (permission) => async (req, res, next) => {
     if (!permission || permission === NONE) {
         return next();
@@ -51,7 +61,7 @@ export default class Controller {
         this.config = config;
     }
 
-    wrap(handler: IRequestHandler): IRequestHandler {
+    private useRouteErrorHandler(handler: IRequestHandler): IRequestHandler {
         return async (req: Request, res: Response) => {
             try {
                 await handler(req, res);
@@ -61,26 +71,46 @@ export default class Controller {
         };
     }
 
-    get(path: string, handler: IRequestHandler, permission?: string): void {
-        this.app.get(
-            path,
-            checkPermission(permission),
-            this.wrap(handler.bind(this)),
+    private useContentTypeMiddleware(options: IRouteOptions): RequestHandler[] {
+        const { middleware = [], acceptedContentTypes = [] } = options;
+
+        return options.acceptAnyContentType
+            ? middleware
+            : [requireContentType(...acceptedContentTypes), ...middleware];
+    }
+
+    route(options: IRouteOptions): void {
+        this.app[options.method](
+            options.path,
+            checkPermission(options.permission),
+            this.useContentTypeMiddleware(options),
+            this.useRouteErrorHandler(options.handler.bind(this)),
         );
     }
 
+    get(path: string, handler: IRequestHandler, permission?: string): void {
+        this.route({
+            method: 'get',
+            path,
+            handler,
+            permission,
+            acceptAnyContentType: true,
+        });
+    }
+
     post(
         path: string,
         handler: IRequestHandler,
         permission: string,
         ...acceptedContentTypes: string[]
     ): void {
-        this.app.post(
+        this.route({
+            method: 'post',
             path,
-            checkPermission(permission),
-            requireContentType(...acceptedContentTypes),
-            this.wrap(handler.bind(this)),
-        );
+            handler,
+            permission,
+            acceptedContentTypes,
+        });
     }
 
     put(
@@ -89,12 +119,13 @@ export default class Controller {
         permission: string,
         ...acceptedContentTypes: string[]
     ): void {
-        this.app.put(
+        this.route({
+            method: 'put',
             path,
-            checkPermission(permission),
-            requireContentType(...acceptedContentTypes),
-            this.wrap(handler.bind(this)),
-        );
+            handler,
+            permission,
+            acceptedContentTypes,
+        });
     }
 
     patch(
@@ -103,20 +134,23 @@ export default class Controller {
         permission: string,
         ...acceptedContentTypes: string[]
     ): void {
-        this.app.patch(
+        this.route({
+            method: 'patch',
             path,
-            checkPermission(permission),
-            requireContentType(...acceptedContentTypes),
-            this.wrap(handler.bind(this)),
-        );
+            handler,
+            permission,
+            acceptedContentTypes,
+        });
     }
 
     delete(path: string, handler: IRequestHandler, permission: string): void {
-        this.app.delete(
+        this.route({
+            method: 'delete',
             path,
-            checkPermission(permission),
-            this.wrap(handler.bind(this)),
-        );
+            handler,
+            permission,
+            acceptAnyContentType: true,
+        });
     }
 
     fileupload(
@@ -129,7 +163,7 @@ export default class Controller {
             path,
             checkPermission(permission),
             filehandler.bind(this),
-            this.wrap(handler.bind(this)),
+            this.useRouteErrorHandler(handler.bind(this)),
         );
     }
 

src/lib/services/addon-service-test-simple-addon.ts

@@ -38,7 +38,7 @@ const definition: IAddonDefinition = {
             sensitive: true,
         },
     ],
-    documentationUrl: 'https:/www.example.com',
+    documentationUrl: 'https://www.example.com',
     events: [
         FEATURE_CREATED,
         FEATURE_UPDATED,

src/lib/services/index.ts

@@ -29,6 +29,7 @@ import FeatureTagService from './feature-tag-service';
 import ProjectHealthService from './project-health-service';
 import UserSplashService from './user-splash-service';
 import { SegmentService } from './segment-service';
+import { OpenApiService } from './openapi-service';
 
 export const createServices = (
     stores: IUnleashStores,
@@ -76,6 +77,7 @@ export const createServices = (
     );
     const userSplashService = new UserSplashService(stores, config);
     const segmentService = new SegmentService(stores, config);
+    const openApiService = new OpenApiService(config);
 
     return {
         accessService,
@@ -106,6 +108,7 @@ export const createServices = (
         projectHealthService,
         userSplashService,
         segmentService,
+        openApiService,
     };
 };
 

src/lib/services/openapi-service.ts

@@ -0,0 +1,62 @@
+import openapi, { ExpressOpenApi } from '@unleash/express-openapi';
+import { Express, RequestHandler } from 'express';
+import { OpenAPIV3 } from 'openapi-types';
+import { IUnleashConfig } from '../types/option';
+import { createOpenApiSchema } from '../openapi';
+import { AdminApiOperation, ClientApiOperation } from '../openapi/types';
+
+export class OpenApiService {
+    private readonly config: IUnleashConfig;
+
+    private readonly api: ExpressOpenApi;
+
+    constructor(config: IUnleashConfig) {
+        this.config = config;
+        this.api = openapi(
+            this.docsPath(),
+            createOpenApiSchema(config.server?.unleashUrl),
+        );
+    }
+
+    // Create request validation middleware for an admin or client path.
+    validPath(op: AdminApiOperation | ClientApiOperation): RequestHandler {
+        return this.api.validPath(op);
+    }
+
+    // Serve the OpenAPI JSON at `${baseUriPath}/docs/openapi.json`,
+    // and the OpenAPI SwaggerUI at `${baseUriPath}/docs/openapi`.
+    useDocs(app: Express): void {
+        app.use(this.api);
+        app.use(this.docsPath(), this.api.swaggerui);
+    }
+
+    // The OpenAPI docs live at `<baseUriPath>/docs/openapi{,.json}`.
+    docsPath(): string {
+        const { baseUriPath = '' } = this.config.server ?? {};
+        return `${baseUriPath}/docs/openapi`;
+    }
+
+    // Add custom schemas to the generated OpenAPI spec.
+    // Used by unleash-enterprise to add its own schemas.
+    registerCustomSchemas(schemas: {
+        [name: string]: OpenAPIV3.SchemaObject;
+    }): void {
+        Object.entries(schemas).forEach(([name, schema]) => {
+            this.api.schema(name, schema);
+        });
+    }
+
+    // Catch and format Open API validation errors.
+    useErrorHandler(app: Express): void {
+        app.use((err, req, res, next) => {
+            if (err && err.status && err.validationErrors) {
+                res.status(err.status).json({
+                    error: err.message,
+                    validation: err.validationErrors,
+                });
+            } else {
+                next();
+            }
+        });
+    }
+}

src/lib/types/mutable.ts

@@ -0,0 +1,9 @@
+// Remove readonly modifiers from properties.
+export type Mutable<T> = {
+    -readonly [P in keyof T]: T[P];
+};
+
+// Recursively remove readonly modifiers from properties.
+export type DeepMutable<T> = {
+    -readonly [P in keyof T]: DeepMutable<T[P]>;
+};

src/lib/types/openapi.d.ts

@@ -0,0 +1,13 @@
+// Partial types for "@unleash/express-openapi".
+declare module '@unleash/express-openapi' {
+    import { RequestHandler } from 'express';
+    import { OpenAPIV3 } from 'openapi-types';
+
+    export interface ExpressOpenApi extends RequestHandler {
+        validPath: (operation: OpenAPIV3.OperationObject) => RequestHandler;
+        schema: (name: string, schema: OpenAPIV3.SchemaObject) => void;
+        swaggerui: RequestHandler;
+    }
+
+    export default function openapi(docsPath: string, any): ExpressOpenApi;
+}

src/lib/types/services.ts

@@ -25,6 +25,7 @@ import ProjectHealthService from '../services/project-health-service';
 import ClientMetricsServiceV2 from '../services/client-metrics/metrics-service-v2';
 import UserSplashService from '../services/user-splash-service';
 import { SegmentService } from '../services/segment-service';
+import { OpenApiService } from '../services/openapi-service';
 
 export interface IUnleashServices {
     accessService: AccessService;
@@ -55,4 +56,5 @@ export interface IUnleashServices {
     versionService: VersionService;
     userSplashService: UserSplashService;
     segmentService: SegmentService;
+    openApiService: OpenApiService;
 }

src/lib/util/serialize-dates.test.ts

@@ -0,0 +1,16 @@
+import { serializeDates } from './serialize-dates';
+
+test('serializeDates', () => {
+    const obj = {
+        a: 1,
+        b: '2',
+        c: new Date(),
+        d: { e: new Date() },
+    };
+
+    expect(serializeDates({})).toEqual({});
+    expect(serializeDates(obj).a).toEqual(1);
+    expect(serializeDates(obj).b).toEqual('2');
+    expect(typeof serializeDates(obj).c).toEqual('string');
+    expect(typeof serializeDates(obj).d.e).toEqual('object');
+});

src/lib/util/serialize-dates.ts

@@ -0,0 +1,18 @@
+type SerializedDates<T> = {
+    [P in keyof T]: T[P] extends Date ? string : T[P];
+};
+
+// Serialize top-level date values to strings.
+export const serializeDates = <T extends object>(
+    obj: T,
+): SerializedDates<T> => {
+    const entries = Object.entries(obj).map(([k, v]) => {
+        if (v instanceof Date) {
+            return [k, v.toJSON()];
+        } else {
+            return [k, v];
+        }
+    });
+
+    return Object.fromEntries(entries);
+};

src/test/config/test-config.ts

@@ -18,13 +18,10 @@ export function createTestConfig(config?: IUnleashOptions): IUnleashConfig {
         getLogger,
         authentication: { type: IAuthType.NONE, createAdminUser: false },
         server: { secret: 'really-secret' },
-        session: {
-            db: false,
-        },
-        experimental: {
-            segments: experimentalSegmentsConfig(),
-        },
+        session: { db: false },
+        experimental: { segments: experimentalSegmentsConfig() },
         versionCheck: { enable: false },
+        enableOAS: true,
     };
     const options = mergeAll<IUnleashOptions>([testConfig, config]);
     return createConfig(options);

src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap

@@ -0,0 +1,411 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`should serve the OpenAPI UI 1`] = `
+"<!DOCTYPE html>
+<html>
+  <head>
+    <title>Swagger UI</title>
+    <meta charset=\\"utf-8\\"/>
+    <meta name=\\"viewport\\" content=\\"width=device-width, initial-scale=1\\">
+    <style>
+      html {
+          box-sizing: border-box;
+          overflow: -moz-scrollbars-vertical;
+          overflow-y: scroll;
+      }
+      *,
+      *:before,
+      *:after {
+          box-sizing: inherit;
+      }
+      body {
+        margin: 0;
+        padding: 0;
+        background: #fafafa;
+      }
+    </style>
+    
+      <link rel=\\"stylesheet\\" type=\\"text/css\\" href=\\"./swagger-ui.css\\" >
+    
+  </head>
+  <body>
+    
+      <div id=\\"swagger-ui\\"></div>
+      <script src=\\"./swagger-ui-bundle.js\\"></script>
+      <script src=\\"./swagger-ui-standalone-preset.js\\"></script>
+      <script>
+        window.onload = function () {
+          window.ui = SwaggerUIBundle({
+            url: \\"/docs/openapi.json\\",
+            dom_id: '#swagger-ui'
+          })
+        }
+      </script>
+    
+  </body>
+</html>
+  "
+`;
+
+exports[`should serve the OpenAPI spec 1`] = `
+Object {
+  "components": Object {
+    "schemas": Object {
+      "constraintSchema": Object {
+        "properties": Object {
+          "contextName": Object {
+            "type": "string",
+          },
+          "operator": Object {
+            "type": "string",
+          },
+          "values": Object {
+            "items": Object {
+              "type": "string",
+            },
+            "type": "array",
+          },
+        },
+        "required": Array [
+          "contextName",
+          "operator",
+        ],
+        "type": "object",
+      },
+      "createFeatureSchema": Object {
+        "properties": Object {
+          "description": Object {
+            "type": "string",
+          },
+          "impressionData": Object {
+            "type": "boolean",
+          },
+          "name": Object {
+            "type": "string",
+          },
+          "type": Object {
+            "type": "string",
+          },
+        },
+        "required": Array [
+          "name",
+        ],
+        "type": "object",
+      },
+      "featureSchema": Object {
+        "properties": Object {
+          "createdAt": Object {
+            "format": "date",
+            "nullable": true,
+            "type": "string",
+          },
+          "description": Object {
+            "type": "string",
+          },
+          "enabled": Object {
+            "type": "boolean",
+          },
+          "impressionData": Object {
+            "type": "boolean",
+          },
+          "lastSeenAt": Object {
+            "format": "date",
+            "nullable": true,
+            "type": "string",
+          },
+          "name": Object {
+            "type": "string",
+          },
+          "project": Object {
+            "type": "string",
+          },
+          "stale": Object {
+            "type": "boolean",
+          },
+          "strategies": Object {
+            "items": Object {
+              "$ref": "#/components/schemas/strategySchema",
+            },
+            "type": "array",
+          },
+          "type": Object {
+            "type": "string",
+          },
+          "variants": Object {
+            "items": Object {
+              "$ref": "#/components/schemas/variantSchema",
+            },
+            "type": "array",
+          },
+        },
+        "required": Array [
+          "name",
+          "project",
+        ],
+        "type": "object",
+      },
+      "featuresSchema": Object {
+        "properties": Object {
+          "features": Object {
+            "items": Object {
+              "$ref": "#/components/schemas/featureSchema",
+            },
+            "type": "array",
+          },
+          "version": Object {
+            "type": "integer",
+          },
+        },
+        "required": Array [
+          "version",
+          "features",
+        ],
+        "type": "object",
+      },
+      "overrideSchema": Object {
+        "properties": Object {
+          "contextName": Object {
+            "type": "string",
+          },
+          "values": Object {
+            "items": Object {
+              "type": "string",
+            },
+            "type": "array",
+          },
+        },
+        "required": Array [
+          "contextName",
+          "values",
+        ],
+        "type": "object",
+      },
+      "strategySchema": Object {
+        "properties": Object {
+          "constraints": Object {
+            "items": Object {
+              "$ref": "#/components/schemas/constraintSchema",
+            },
+            "type": "array",
+          },
+          "id": Object {
+            "type": "string",
+          },
+          "name": Object {
+            "type": "string",
+          },
+          "parameters": Object {
+            "type": "object",
+          },
+        },
+        "required": Array [
+          "id",
+          "name",
+          "constraints",
+          "parameters",
+        ],
+        "type": "object",
+      },
+      "variantSchema": Object {
+        "properties": Object {
+          "name": Object {
+            "type": "string",
+          },
+          "overrides": Object {
+            "items": Object {
+              "$ref": "#/components/schemas/overrideSchema",
+            },
+            "type": "array",
+          },
+          "payload": Object {
+            "type": "object",
+          },
+          "stickiness": Object {
+            "type": "string",
+          },
+          "weight": Object {
+            "type": "number",
+          },
+          "weightType": Object {
+            "type": "string",
+          },
+        },
+        "required": Array [
+          "name",
+          "weight",
+          "weightType",
+          "stickiness",
+          "overrides",
+        ],
+        "type": "object",
+      },
+    },
+    "securitySchemes": Object {
+      "apiKey": Object {
+        "in": "header",
+        "name": "Authorization",
+        "type": "apiKey",
+      },
+    },
+  },
+  "info": Object {
+    "title": "Unleash API",
+  },
+  "openapi": "3.0.3",
+  "paths": Object {
+    "/api/admin/archive/features": Object {
+      "get": Object {
+        "deprecated": true,
+        "responses": Object {
+          "200": Object {
+            "content": Object {
+              "application/json": Object {
+                "schema": Object {
+                  "$ref": "#/components/schemas/featuresSchema",
+                },
+              },
+            },
+            "description": "featuresResponse",
+          },
+        },
+        "tags": Array [
+          "admin",
+        ],
+      },
+    },
+    "/api/admin/features/": Object {
+      "get": Object {
+        "deprecated": true,
+        "responses": Object {
+          "200": Object {
+            "content": Object {
+              "application/json": Object {
+                "schema": Object {
+                  "$ref": "#/components/schemas/featuresSchema",
+                },
+              },
+            },
+            "description": "featuresResponse",
+          },
+        },
+        "tags": Array [
+          "admin",
+        ],
+      },
+    },
+    "/api/admin/projects/{projectId}/features": Object {
+      "get": Object {
+        "parameters": Array [
+          Object {
+            "in": "path",
+            "name": "projectId",
+            "required": true,
+            "schema": Object {
+              "type": "string",
+            },
+          },
+        ],
+        "responses": Object {
+          "200": Object {
+            "content": Object {
+              "application/json": Object {
+                "schema": Object {
+                  "$ref": "#/components/schemas/featuresSchema",
+                },
+              },
+            },
+            "description": "featuresResponse",
+          },
+        },
+        "tags": Array [
+          "admin",
+        ],
+      },
+      "post": Object {
+        "parameters": Array [
+          Object {
+            "in": "path",
+            "name": "projectId",
+            "required": true,
+            "schema": Object {
+              "type": "string",
+            },
+          },
+        ],
+        "requestBody": Object {
+          "content": Object {
+            "application/json": Object {
+              "schema": Object {
+                "$ref": "#/components/schemas/createFeatureSchema",
+              },
+            },
+          },
+          "required": true,
+        },
+        "responses": Object {
+          "200": Object {
+            "content": Object {
+              "application/json": Object {
+                "schema": Object {
+                  "$ref": "#/components/schemas/featureSchema",
+                },
+              },
+            },
+            "description": "featureResponse",
+          },
+        },
+        "tags": Array [
+          "admin",
+        ],
+      },
+    },
+    "/api/admin/projects/{projectId}/features/{featureName}": Object {
+      "get": Object {
+        "parameters": Array [
+          Object {
+            "in": "path",
+            "name": "projectId",
+            "required": true,
+            "schema": Object {
+              "type": "string",
+            },
+          },
+          Object {
+            "in": "path",
+            "name": "featureName",
+            "required": true,
+            "schema": Object {
+              "type": "string",
+            },
+          },
+        ],
+        "responses": Object {
+          "200": Object {
+            "content": Object {
+              "application/json": Object {
+                "schema": Object {
+                  "$ref": "#/components/schemas/featureSchema",
+                },
+              },
+            },
+            "description": "featureResponse",
+          },
+        },
+        "tags": Array [
+          "admin",
+        ],
+      },
+    },
+  },
+  "security": Array [
+    Object {
+      "apiKey": Array [],
+    },
+  ],
+  "servers": Array [
+    Object {
+      "url": "http://localhost:4242",
+    },
+  ],
+}
+`;

src/test/e2e/api/openapi/openapi.e2e.test.ts

@@ -0,0 +1,38 @@
+import { setupApp } from '../../helpers/test-helper';
+import dbInit from '../../helpers/database-init';
+import getLogger from '../../../fixtures/no-logger';
+
+let app;
+let db;
+
+beforeAll(async () => {
+    db = await dbInit('openapi', getLogger);
+    app = await setupApp(db.stores);
+});
+
+afterAll(async () => {
+    await app.destroy();
+    await db.destroy();
+});
+
+test('should serve the OpenAPI UI', async () => {
+    return app.request
+        .get('/docs/openapi/')
+        .expect('Content-Type', /html/)
+        .expect(200)
+        .expect((res) => expect(res.text).toMatchSnapshot());
+});
+
+test('should serve the OpenAPI spec', async () => {
+    return app.request
+        .get('/docs/openapi.json')
+        .expect('Content-Type', /json/)
+        .expect(200)
+        .expect((res) => {
+            // The version field is not set when running jest without yarn/npm.
+            delete res.body.info.version;
+            // This test will fail whenever there's a change to the API spec.
+            // If the change is intended, update the snapshot with `jest -u`.
+            expect(res.body).toMatchSnapshot();
+        });
+});

tsconfig.json

@@ -45,7 +45,6 @@
     // "paths": {},                           /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */
     // "rootDirs": [],                        /* List of root folders whose combined content represents the structure of the project at runtime. */
     // "typeRoots": [],                       /* List of folders to include type definitions from. */
-    // "types": [],                           /* Type declaration files to be included in compilation. */
     // "allowSyntheticDefaultImports": true,  /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
     "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
     // "preserveSymlinks": true,              /* Do not resolve the real path of symlinks. */
@@ -64,6 +63,9 @@
     "skipLibCheck": true /* Skip type checking of declaration files. */,
     "forceConsistentCasingInFileNames": true /* Disallow inconsistently-cased references to the same file. */
   },
+  "types": [
+    "src/types/openapi.d.ts"
+  ],
   "exclude": [
     "bin",
     "docs",