# ts-openapi > An openapi json generator based on joi information about APIs that will help you to maintain your API documentation up to date. Latest version **1.1.11** (published 2026-06-23) · ISC license · 0 weekly downloads ## Install ```sh npm install ts-openapi pnpm add ts-openapi yarn add ts-openapi bun add ts-openapi ``` ## Health **Score 65/100 (B)** — status: active. Positive: has types; no vulnerabilities; recently updated; high maintenance score; high quality score. Warnings: low downloads; no esm support. ## Facts | | | |---|---| | Version | 1.1.11 | | Published | 2026-06-23 | | First published | 2020-11-10 | | Weekly downloads | 0 | | License | ISC | | TypeScript types | bundled | | Module format | CommonJS | | Node | >=20 | | Dependencies | 4 | | Unpacked size | 188.3 KB | | Known vulnerabilities | 0 (+12 in 2 direct dependencies) | | Install scripts | no | | GitHub stars | 17 | | Author | Nelson Gomes | | Maintainers | nelson.gomes | | Keywords | openapi, api, documenting, typescript | ## Links - npm: https://www.npmjs.com/package/ts-openapi - Repository: https://github.com/nelsongomes/ts-openapi - Homepage: https://github.com/nelsongomes/ts-openapi#readme - Issues: https://github.com/nelsongomes/ts-openapi/issues - npm.io page: https://npm.io/package/ts-openapi ## Dependencies (4) - [joi](https://npm.io/package/joi.md) 17.13.4 - [axios](https://npm.io/package/axios.md) 1.17.0 - [lodash](https://npm.io/package/lodash.md) 4.18.1 - [node-object-hash](https://npm.io/package/node-object-hash.md) 2.3.10 ## Alternatives - [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads - [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads - [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads - [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads - [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads ## Recent versions - 1.1.11 (latest) — 2026-06-23 - 1.1.10 — 2025-10-06 - 1.1.9 — 2025-07-28 - 1.1.8 — 2024-11-20 - 1.1.7 — 2024-02-25 - 1.1.6 — 2023-07-22 - 1.1.5 — 2023-05-20 - 1.1.4 — 2022-09-07 - 1.1.3 — 2022-09-07 - 1.1.2 — 2022-06-17 - 1.1.0 — 2022-04-28 - 1.0.3 — 2022-02-03 - 1.0.2 — 2022-01-07 - 1.0.1 — 2022-01-07 - 1.0.0 — 2022-01-06 - … 14 more at https://npm.io/package/ts-openapi/versions ## README # Ts-openapi [![npm](https://img.shields.io/npm/v/ts-openapi.svg)](https://www.npmjs.com/package/ts-openapi) An openapi json generator using joi API schemas that will help you to maintain your API documentation up to date. Joi is the is one of the most used components to validate data schemas, this can be used to generate and maintain API information up to date, without the need to update manually documentation. This software has some code extracted from [joi-to-swagger](https://www.npmjs.com/package/joi-to-swagger) to interface with Joi schemas. ## Installation Using npm: `npm i --save ts-openapi` ### Visit the [GitHub Repo](https://github.com/nelsongomes/ts-openapi/) tutorials, documentation, and support ------------ ## OpenApi Supported Types Type | Query | Path (1)(5) | Header | Cookie | Body -------------------------------------------- | ------- | --------- | ------ | ------- | --------- String, String Enum, Email, Password, Uuid, Uri, Hostname, Ipv4, Ipv6 | YES | YES | YES | YES | NO (4) Integer, Integer Enum, Number, Number Enum | YES | YES | YES | YES | NO (4) Date-time, Date | YES | YES | YES | YES | NO (4) Byte(3), Binary (string) | YES | YES | YES | YES | NO (4) Array[] | YES (3) | NO | NO | NO | YES (4) Object | NO | NO | NO | NO | YES (6) (1) Values included in url parameters are always required because they're part of the url.
(2) this type is a Base64 binary encoded string.
(3) array of scalar values.
(4) for body we support objects and arrays.
(5) the name of route parameters must be made up of “word characters” ([A-Za-z0-9_]).
(6) GET requests don't have a body.
 ## Type Samples ### All samples presented here an in Typescript [String Types](documentation/STRING.md)
[Numeric Types](documentation/NUMERIC.md)
[Date-Time Types](documentation/DATE-TIME.md)
[Binary Types](documentation/BINARY.md)
[Array Type](documentation/ARRAY.md)
[Object Type](documentation/OBJECT.md)
## Advanced Topics ### Security [Security Schemes](documentation/SECURITY.md)
### Parameters and Models [Parameters and Models](documentation/PARAMETERS-AND-MODELS.md)
### Mingle multiple services [Mingle multiple services](documentation/COMBINED.md)
## Declaring an API ### First we need to create an OpenApi object to store information ```ts const openApi = new OpenApi( "1.0.0", // API version "Server API", // API title "Some test api", // API description "maintainer@domain.com" // API maintainer email ); ``` ### Then you need to declare an array with the API servers In the event your API is based on docker instances you should call setServers when OpenApi class is called to get the json, to update the IPs and port numbers. You can even specify different servers depending if the call is internal or external. Up to you. ```ts openApi.setServers([ { url: "https://api.domain.com:443" }, { url: "https://192.168.1.23:80" } ]); ``` ### Optionally you can set your license information This is used to document the API license type, url of the license and terms of service. ```ts openApi.setLicense( "Apache 2.0", // license name "http://www.apache.org/licenses/LICENSE-2.0.html", // url for the api license "http://swagger.io/terms/" // terms of service ); ``` ### Now you need to declare your endpoints (once per http verb) ```ts openApi.addPath( "/hello", { get: { summary: "Server Healthcheck", // Method title description: "Hello world endpoint", // Method description operationId: "hello-op", // unique operation id responses: { // response codes and description 200: textPlain("Successful operation."), /* // or if you prefer: 200: { description: "Successful operation.", content: { "text-plain": {} }, // mimetype with empty schema },*/ }, tags: ["Test Operations"], // One or more tags, this will allow API grouping }, }, true // visible ? If not it gets skipped from declaration ); ``` ### Finally we export the JSON schema Note that the paths just need to be added one time, during server init, after this the openApi is basically static. ```ts openApi.generateJson(); ``` ## Declaring a GET request ```ts const errorSchema = Types.Object({ description: "Error description", properties: { message: Types.String({ description: "Error message" }), code: Types.Integer({ description: "Error code" }), }, example: { message: "Bad request": code: 400 } }); // body response schema const responseSchema = Types.Object({ description: "Customer details", properties: { id: Types.Uuid({ description: "Customer ID" }), name: Types.String({ description: "Customer name", maxLength: 100, required: true, }), type: Types.StringEnum({ values: Object.values(CustomerType), description: "Customer Type", }), birthdate: Types.Date({ description: "Birthdate" }), }, example: { id: "96efe677-f752-426f-a9b8-b9f33b286cc9", name: "customer model", type: "gold", birthdate: "11-11-1911" }, }); openApi.addPath( "/customer/:id", // path parameter { get: { summary: "Get a customer data", description: "This operation retrieves customer information", operationId: "get-customer-op", requestSchema: { params: { // path parameter id: Types.Uuid({ description: "Customer ID", required: true, // param values MUST be required example: "37237d6a-bb7e-459a-b75d-d1733210ad5c", }), }, }, tags: ["Customer Operations"], responses: { 200: openApi.declareSchema("Get customer success", responseSchema), 400: openApi.declareSchema("Bad Request", errorSchema), }, }, }, true ); ``` ## Declaring other HTTP methods You can declare: * delete requests * get requests * patch requests * post requests * put methods ## Declaring the inputs of your request When you declare your request you can use as inputs: * query parameters '?a=1&b=2' * param parameter '/:userid/list' * cookie parameter (a cookie) * header parameters * body content ## Sample server [GitHub Repo for a demo server](https://github.com/nelsongomes/server) ## Medium Articles [Maintaining REST API Documentation with Node.js — Part I](https://medium.com/p/65e9700e3b30) about documenting a single service
[Maintaining REST API Documentation with Node.js — Part II](https://medium.com/p/26d1a622d3fe) about combining multiple services documentation --- _Source: https://npm.io/package/ts-openapi · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._