https://github.com/lukeautry/tsoa

Build OpenAPI-compliant REST APIs using TypeScript and Node
https://github.com/lukeautry/tsoa

hacktoberfest hacktoberfest2021

Last synced: 7 days ago
JSON representation

Build OpenAPI-compliant REST APIs using TypeScript and Node

• Host: GitHub
• URL: https://github.com/lukeautry/tsoa
• Owner: lukeautry
• License: mit
• Created: 2016-06-17T10:42:50.000Z (over 8 years ago)
• Default Branch: master
• Last Pushed: 2024-10-24T12:25:21.000Z (12 days ago)
• Last Synced: 2024-10-28T12:25:04.899Z (8 days ago)
• Topics: hacktoberfest, hacktoberfest2021
• Language: TypeScript
• Homepage:
• Size: 6.64 MB
• Stars: 3,536
• Watchers: 28
• Forks: 499
• Open Issues: 106
• Metadata Files:
  • Readme: README.MD
  • Contributing: docs/CONTRIBUTING.md
  • License: LICENSE
  • Security: SECURITY.md

Awesome Lists containing this project

• awesome-github-star - tsoa - compliant REST APIs using TypeScript and Node | lukeautry | 2886 | (TypeScript)

README

        


  

    
tsoa

  

Pronounced so·uh


OpenAPI-compliant REST APIs using TypeScript and Node

![build status](https://github.com/lukeautry/tsoa/actions/workflows/runTestsOnPush.yml/badge.svg)

[![npm version](https://img.shields.io/npm/v/tsoa/latest)](https://www.npmjs.com/package/tsoa)



## Goal

- TypeScript controllers and models as the single source of truth for your API

- A valid OpenAPI (formerly Swagger) spec (2.0 or 3.0 if you choose 😍) is generated from your controllers and models, including:

  - Paths (e.g. GET /users)

  - Definitions based on TypeScript interfaces (models)

  - Parameters/model properties marked as required or optional based on TypeScript (e.g. myProperty?: string is optional in the OpenAPI spec)

  - jsDoc supported for object descriptions (most other metadata can be inferred from TypeScript types)

- Routes are generated for middleware of choice

  - Express, Hapi, and Koa currently supported, other middleware can be supported using a simple handlebars template

  - Validate request payloads

## Philosophy

- Rely on TypeScript type annotations to generate API metadata if possible

- If regular type annotations aren't an appropriate way to express metadata, use decorators

- Use jsdoc for pure text metadata (e.g. endpoint descriptions)

- Minimize boilerplate

- Models are best represented by interfaces (pure data structures), but can also be represented by classes

- Runtime validation of tsoa should behave as closely as possible to the specifications that the generated OpenAPI 2/3 schema describes. Any differences in validation logic are clarified by logging warnings during the generation of the OpenAPI Specification (OAS) and/or the routes.

  - Please note that by enabling OpenAPI 3 you minimize the chances of divergent validation logic since OpenAPI 3 has a more expressive schema syntax.

## Getting Started

- [Documentation](https://tsoa-community.github.io/docs/)

- [API Reference](https://tsoa-community.github.io/reference/)

- [Getting started guide](https://tsoa-community.github.io/docs/getting-started)

## Examples

Check out the [guides](https://tsoa-community.github.io/docs/getting-started)

See example controllers in [the tests](tests/fixtures/controllers)

See example models in [the tests](tests/fixtures/testModel.ts)

## Help wanted

### Contributing code

To contribute (via a PR), please first see the [Contributing Guide](https://github.com/lukeautry/tsoa/tree/master/docs/CONTRIBUTING.md)

### Becoming a maintainer

tsoa wants additional maintainers! The library has increased in popularity and has quite a lot of pull requests and issues. [Please post in this issue](https://github.com/lukeautry/tsoa/issues/236) if you're willing to take on the role of a maintainer.