@skywardapps/ts-openapi-gen NPM

ts-openapi-gen

A generator for OpenApi documentation based on Typescript, Express, Inversify and TypeDoc.

Overview

Code an API using Express and inversifyJS. Comment it using JSDoc...

Endpoint Code

... and type it using Typescript (NOTE: due to typedoc limitations, only supports 4.0 -> 4.7).

Types

Install typedoc and ts-openapi-gen

yarn add --dev typedoc@~0.22 typedoc-plugin-expand-object-like-types@^0.1 typedoc-plugin-missing-exports@^2.1 ts-openapi-gen

Now generate your OpenApi schema directly from your code -- types and comments extracted, inferred, and included!

yarn run typedoc --json ./docs/typedoc.json --entryPointStrategy Expand --disableSources --plugin typedoc-plugin-expand-object-like-types --plugin typedoc-plugin-missing-exports --pretty src/controllers yarn run ts-openapi-gen --entrypoint ./docs/typedoc.json --out assets/public/openapi.json

Generated OpenApi

Getting Started

This presumes you have a RESTful web-api you are building, utilizing Typescript for typing, JSDoc for commenting, and inversify-express-utils to scaffold your API endpoints on top of express.

Requirements:

InversifyJS & inversify-express-utils
Typescript 4.7
Express

Your project must be in buildable state (node_modules installed, code builds, etc). Point ts-openapi-gen to your root tsconfig file and the location of the entrypoints (the controllers).

Generating the OpenApi Schema

ts-openapi-gen has three parameters:

Parameter	Description	Required
--typedoc	The generated typedoc json file.	:heavy_check_mark:
--tsconfig	Points to the tsconfig for your project; required to be able to interpret the types included and referenced; defaults to tsconfig.json in the current directory.
--out	The name of the file to write the schema to; defaults to `openapi.json` if not provided.

Features

Automatically discover published endpoints
Inspect annotations and derive:
- Http Method
- Paths
Inspect JSDoc comments and derive:
- Short and long comments
- Descriptions of parameters and return values
Reflect Typescript types and derive:
- Schemas for POST bodies
- Schemas for API response data
- Automatically unwrap inversify types (Promise, OkNegotiatedContent, etc)