# @winkgroup/ts-swagger

> library to transform typescript declarations into OpenAPI document

Latest version **1.0.2** (published 2023-01-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install @winkgroup/ts-swagger
pnpm add @winkgroup/ts-swagger
yarn add @winkgroup/ts-swagger
bun add @winkgroup/ts-swagger
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2023-01-19 |
| First published | 2023-01-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 27 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | winksrl |
| Maintainers | alexsp84, fairsayan, winksrl |
| Keywords | openapi, swagger, typescript, api, interface, express, crud, schemas |

## Links

- npm: https://www.npmjs.com/package/@winkgroup/ts-swagger
- Repository: https://github.com/WINKgroup/ts-swagger
- Homepage: https://github.com/WINKgroup/ts-swagger#readme
- Issues: https://github.com/WINKgroup/ts-swagger/issues
- npm.io page: https://npm.io/package/@winkgroup/ts-swagger

## Dependencies (6)

- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [@babel/types](https://npm.io/package/@babel/types.md) ^7.20.7
- [@babel/parser](https://npm.io/package/@babel/parser.md) ^7.20.7
- [@types/lodash](https://npm.io/package/@types/lodash.md) ^4.14.191
- [@babel/traverse](https://npm.io/package/@babel/traverse.md) ^7.20.10
- [@types/babel__traverse](https://npm.io/package/@types/babel__traverse.md) ^7.18.3

## 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.0.2 (latest) — 2023-01-19
- 1.0.1 — 2023-01-19
- 1.0.0 — 2023-01-19

## README

# Ts-Swagger

Ts-Swagger is a Javascript library that converts Typescript interfaces and Express APIs into OpenAPI/Swagger JSON.

Ts-Swagger library scans the Typescript files of interest and converts interfaces and APIs marked with specific comments. As a result it provides a JSON composed according to the OpenAPI 3 specification. Optionally generate a file with a .json extension in the project root.

## Installation

```bash
npm i @winkgroup/ts-swagger
```

## Usage

In order to be properly used, Ts-Swagger requires a **configuration file** with the paths containing all of your interfaces/API, along with some other info such as the documentation title (apiName) and version. Other optional info is the description and list of servers.

This file **must be placed at the root** of your project folder.

```JSON
{
    "pathList": [
        "./model/User.ts",
        "./model/Cart.ts",
        "./routes/api/user.js"
    ],
    "apiName": "",
    "version": "",
    "description": "",
    "servers": [
        {
            "url": "http://localhost:3000/",
            "description": "Staging"
        },
    ]
}
```

In order for the library to work, you need to add a **comment** inside every interface that you want to generate Swagger for.
```ts
// swagger
```
```ts

// This interface will be converted 
export interface User {
    // swagger
    name: string,
    id: number
}

// This interface won't be converted
export interface Cart {
    productName: string,
    price: number,
    quantity: number,
    productId: number
}
```


Your **APIs** will also need a comment that specifies **which interface they're using**, otherwise the swagger for them won't be generated.

```js
app.get('/users', function(req, res) {
    // schema: User
    res.send(Users);
});
```

Other optional comments are the description of the API and its response.

```js
app.get('/users', function(req, res) {
    // schema: User
    // description: Get all users
    // response_description: Array of users
    res.send(Users);
});
```

With the following syntax you can also add the description of status codes other than 200 and if you want with an optional comment, you can provide a reference to the Typescript interface that describes the related response.

```js
app.get('/users/:userId', function(req, res) {
    // schema: User
    // {404}: Not found
    // {500}: Some server error
    // error_schema: Error
    res.send(User);
});
```

The library exposes a method called **getSwagger()** that returns the Swagger JSON. If a **filename** is provided as an argument, a new file containing the JSON will be created in the root of your project.

```js
import { TsSwagger } from "@winkgroup/ts-swagger";

// Configuration file path must be passed inside class constructor
const tsswg = new TsSwagger("../tsswagger.config.json");

// Returns the JSON Swagger
const swaggerObj = tsswg.getSwagger();

// Creates the JSON Swagger file
tsswg.getSwagger('swagger.json');

```

## Maintainers
* [fairsayan](https://github.com/fairsayan)
* [alexSp84](https://github.com/alexSp84)
* [simonechebelnome](https://github.com/simonechebelnome)

## License

[MIT](https://choosealicense.com/licenses/mit/)

---
_Source: https://npm.io/package/@winkgroup/ts-swagger · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._