{"id":14155330,"url":"https://github.com/Eywek/typoa","last_synced_at":"2025-08-06T01:30:57.215Z","repository":{"id":46239156,"uuid":"308694709","full_name":"Eywek/typoa","owner":"Eywek","description":"🏗 Build OpenAPI definitions from Typescript typings","archived":false,"fork":false,"pushed_at":"2024-09-19T16:10:12.000Z","size":310,"stargazers_count":26,"open_issues_count":8,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-12-05T22:40:55.451Z","etag":null,"topics":["codegen","express","openapi","openapi-generator","swagger","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Eywek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-30T17:06:53.000Z","updated_at":"2024-11-29T17:10:06.000Z","dependencies_parsed_at":"2022-09-20T11:13:49.080Z","dependency_job_id":null,"html_url":"https://github.com/Eywek/typoa","commit_stats":null,"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eywek%2Ftypoa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eywek%2Ftypoa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eywek%2Ftypoa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eywek%2Ftypoa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Eywek","download_url":"https://codeload.github.com/Eywek/typoa/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228821404,"owners_count":17977166,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codegen","express","openapi","openapi-generator","swagger","typescript"],"created_at":"2024-08-17T08:02:51.058Z","updated_at":"2025-08-06T01:30:57.205Z","avatar_url":"https://github.com/Eywek.png","language":"TypeScript","funding_links":[],"categories":["typescript"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n  \u003ch1\u003etypoa\u003c/h1\u003e\n  \u003ch2\u003e \u003cb\u003eTyp\u003c/b\u003eescript \u003cb\u003eO\u003c/b\u003epen\u003cb\u003eA\u003c/b\u003ePI Generator\u003c/h2\u003e\n\n  This tools is inspired from [tsoa](https://github.com/lukeautry/tsoa), the purpose is to be able to generate openapi definitions and express routes definitions via Typescript typings.\n\n  We're using [ts-morph](https://github.com/dsherret/ts-morph) under the hood.\n\n\u003c/div\u003e\n\n## Why\n\nTsoa is a great package and it's working fine for simple typescript typings, which I think are principal use cases, it's used by many developers and maintained.\n\n**BUT**, I've used tsoa in production projects and I've encountered many issues (I was able to [fix](https://github.com/lukeautry/tsoa/pulls?q=is%3Apr+sort%3Aupdated-desc+is%3Amerged+author%3AEywek) some of them), but when I've tried to use more complex types (inheritance, deep generics, conditionnal types...) tsoa wasn't able to provide me good openapi definitions, and without even telling me it failed to generate the right schema.\n\nI've spent a lot of time trying to fix those issues, using tricks to have a workaround. But it was never perfect, I've ended with too many duplicated types only because tsoa was not able to resolve correct typings. I wasn't confident when updating my models and I was always checking that the swagger wasn't broken.\n\nAnd all of this issues are caused by the custom type resolver of tsoa, in this package we're using `ts-morph`, it allows us to build a resolver more resilient that handle all cases without maintenance on our side.\n\n## Features\n\n- Generate express router via typescript decorators in controllers\n- Generate openapi definition via typescript typings\n- Allowing to export custom types to openapi schema\n- Runtime validation against openapi schema\n- Use jsdoc for additionnal configuration (example, regex...)\n- Handle getters only and readonly properties\n\n## How to use\n\n### Define your controllers\n\nYou only need to add the `@Route()` decorator at the top of your controller class and `@Get()`, `@Post()`... at the top\nof each method definition, like this:\n\n```ts\nimport { Route, Get } from 'typoa'\n\n@Route()\nclass MyController {\n  @Get()\n  public get () {}\n}\n```\n\nYou can provide the route path in the `@Route()` decorator or in each verb decorators (eg. `@Get`...) or both.\n\nYou also will need to extends the `Controller` class if you want to override the default HTTP status (200 if your method return content, 204 if not):\n\n```ts\nimport { Route, Get, Controller } from 'typoa'\n\n@Route('/controller-path')\nclass MyController extends Controller {\n  @Get('/method-path')\n  public get () {\n    this.setStatus(201)\n    return 'Created'\n  }\n}\n```\n\nTo send data to the client you only need to return your data, `typoa` will use `res.json()` with it.\nIf you return a stream, `typoa` will stream it to the client.\n\n#### Body, Query, Path, Header and Request\n\nTo use the parsed (and validated) body from typoa you only need to provide the `@Body()` decorator:\n\n```ts\nimport { Route, Get, Controller } from 'typoa'\n\n@Route('/controller-path')\nclass MyController extends Controller {\n  @Post('/method-path')\n  public post (\n    @Body() body: { name: string }\n  ) {\n    this.setStatus(201)\n    return 'Created'\n  }\n}\n```\n\nThis is the same for query parameters (`@Query('\u003cname\u003e')`), path parameters (`@Path('\u003cname\u003e')`) and headers (`@Header('\u003cname\u003e')`).\n\nYou also can use the `@Request()` decorator if you need to access the express request.\n\n**Note:** You can see more examples in the `example/` folder.\n\n##### Body discrimination\n\nSometimes you want to validate the body against a specific schema depending on which resource the user try to update...\n\nTo handle that, you can provide a `discriminator function` to the body decorator:\n\n```ts\nimport { Route, Get, Controller, BodyDiscriminatorFunction } from 'typoa'\n\ntype TypeA = { name: string }\ntype TypeB = { name: number }\n\n// The function need to return the name of the type you want to validate against\nexport const discriminatorFunction: BodyDiscriminatorFunction = async (req) =\u003e 'TypeA'\n\n@Route('/controller-path')\nclass MyController extends Controller {\n  @Post('/method-path')\n  public post (\n    @Body(\n      'application/json', // body content-type\n      discriminatorFunction // name of the function you want to use\n    ) body: TypeA | TypeB\n  ) {\n    this.setStatus(201)\n    return 'Created'\n  }\n}\n```\n\n### Generate\n\nTo generate the openapi definition and the router you will need to bind to express, you only need to call the `generate` method of `typoa`:\n\n```ts\nawait generate({\n  tsconfigFilePath: path.resolve(__dirname, './tsconfig.json'),\n  controllers: [path.resolve(__dirname, './*.ts')], // Path of your controllers\n  openapi: {\n    // Where do you want to generate your openapi file (or array of file paths)\n    // The file extension (.json, .yaml, or .yml) determines the output format\n    filePath: '/tmp/openapi.json',\n    service: { // Used in the openapi definitions\n      name: 'my-service',\n      version: '1.0.0'\n    },\n    securitySchemes: { // Openapi securitySchemes definitions\n      company: {\n        type: 'apiKey',\n        name: 'x-company-id',\n        in: 'header'\n      }\n    }\n  },\n  router: {\n    filePath: './router.ts', // Where do you want to generate the router file\n    securityMiddlewarePath: './security.ts' // Optional, middleware called if you use the @Security() decorator\n  }\n})\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEywek%2Ftypoa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEywek%2Ftypoa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEywek%2Ftypoa/lists"}