# swagger-controllers

> Generate swagger.json file from opinionated controllers

Latest version **1.0.7** (published 2019-07-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install swagger-controllers
pnpm add swagger-controllers
yarn add swagger-controllers
bun add swagger-controllers
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.7 |
| Published | 2019-07-31 |
| First published | 2019-07-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 270.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Jay Baker |
| Maintainers | logikaljay |
| Keywords | tsoa, swagger, typescript |

## Links

- npm: https://www.npmjs.com/package/swagger-controllers
- npm.io page: https://npm.io/package/swagger-controllers

## Dependencies (5)

- [bpc](https://npm.io/package/bpc.md) 0.0.1
- [moment](https://npm.io/package/moment.md) ^2.24.0
- [yamljs](https://npm.io/package/yamljs.md) ^0.3.0
- [lodash.map](https://npm.io/package/lodash.map.md) ^4.6.0
- [lodash.indexof](https://npm.io/package/lodash.indexof.md) ^4.0.5

## 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.7 (latest) — 2019-07-31
- 1.0.6 — 2019-07-25
- 1.0.5 — 2019-07-25
- 1.0.4 — 2019-07-25
- 1.0.3 — 2019-07-25
- 1.0.2 — 2019-07-25
- 1.0.1 — 2019-07-24
- 1.0.0 — 2019-07-24
- 0.0.6 — 2019-07-24
- 0.0.5 — 2019-07-24
- 0.0.4 — 2019-07-24
- 0.0.3 — 2019-07-24
- 0.0.2 — 2019-07-24
- 0.0.1 — 2019-07-24

## README

# swagger-controllers

Convert opinionated typescript ES6 classes to swagger documentation.

The bulk of this work is taken from [tsoa](https://github.com/lukeautry/tsoa). A big thanks to all of the contributors to that project.

## Why not just use tsoa?

Running a command to generate express routes from classes never sat well with me, mostly due to debugging.

## Is this a replacement for tsoa?

Not at all. All this library does is use typescript to generate a swagger.json file from classes that have been defined. It is up to you to convert these classes to routes somehow.

## Example

```typescript
import { Controller } from "swagger-controllers";

interface IDtoName {
  first: string
  middle?: string
  last: string
}

interface IDtoInput {
  id: number
  name: IDtoName
}

interface IDtoOutput {
  success: boolean
  details: {
    id: number
    name: IDtoName
  }
}


@Controller("/api/test")
export class TestController {
  public async GetTest(id: string): Promise<string> {
    return "";
  }

  public async CreateOrUpdateTest(input: IDtoInput): Promise<IDtoOutput> {
    return {
      success: true,
      details: {
        id: 1,
        name: {
          first: "robert",
          middle: "bob",
          last: "jones"
        }
      }
    }
  }
}
```

The above example ES6 Typescript class will produce a swagger.json schema file with 3 definitions and 2 API endpoints.


## How to use

```typescript
import * as express from "express"
import * as swagger from "swagger-ui-express"
import GenerateDocument, { SwaggerConfig } from "swagger-controllers"

// load any es6 controllers by path
import './controllers/TestController'

// see SwaggerConfig interface for complete options
const config: SwaggerConfig = {
  entryFile: "./src/index", // entry file to your project for typescript to open
  basePath: "/",            // base api path
  outputDirectory: "./"     // path to where the swagger.json will be generated
}

// genearte a JSON Swagger.Spec object.
const document = GenerateDocument(config)

// usual express/swagger-ui-express stuff.
const app = express()
app.use('/docs', swagger.serve, swagger.setup(document))
app.listen(8888, () => {
  console.log("Swagger ready on http://localhost:8888/docs")
})
```

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