{"id":343882,"url":"https://github.com/thiagobustamante/typescript-rest-swagger","last_synced_at":"2025-04-04T10:08:37.690Z","repository":{"id":20704575,"uuid":"89664607","full_name":"thiagobustamante/typescript-rest-swagger","owner":"thiagobustamante","description":"Swagger tools for typescript-rest","archived":false,"fork":false,"pushed_at":"2024-05-26T05:15:34.000Z","size":795,"stargazers_count":156,"open_issues_count":75,"forks_count":57,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-30T01:38:28.841Z","etag":null,"topics":["decorators","rest","swagger-decorators","swagger-documentation","swagger-generator","typescript","typescript-rest"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thiagobustamante.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-28T03:39:07.000Z","updated_at":"2024-07-29T13:01:27.000Z","dependencies_parsed_at":"2024-11-21T10:16:01.676Z","dependency_job_id":null,"html_url":"https://github.com/thiagobustamante/typescript-rest-swagger","commit_stats":{"total_commits":176,"total_committers":26,"mean_commits":6.769230769230769,"dds":0.7556818181818181,"last_synced_commit":"a0dd006e003a3f1ae256db87f33c6d2dadc3cb63"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiagobustamante%2Ftypescript-rest-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiagobustamante%2Ftypescript-rest-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiagobustamante%2Ftypescript-rest-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiagobustamante%2Ftypescript-rest-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thiagobustamante","download_url":"https://codeload.github.com/thiagobustamante/typescript-rest-swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247157098,"owners_count":20893214,"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":["decorators","rest","swagger-decorators","swagger-documentation","swagger-generator","typescript","typescript-rest"],"created_at":"2024-01-07T12:47:09.327Z","updated_at":"2025-04-04T10:08:37.659Z","avatar_url":"https://github.com/thiagobustamante.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"[![npm version](https://badge.fury.io/js/typescript-rest-swagger.svg)](https://badge.fury.io/js/typescript-rest-swagger)\n![Master Workflow](https://github.com/thiagobustamante/typescript-rest-swagger/workflows/Master%20Workflow/badge.svg)\n[![Coverage Status](https://coveralls.io/repos/github/thiagobustamante/typescript-rest-swagger/badge.svg?branch=master)](https://coveralls.io/github/thiagobustamante/typescript-rest-swagger?branch=master)\n[![Known Vulnerabilities](https://snyk.io/test/github/thiagobustamante/typescript-rest-swagger/badge.svg?targetFile=package.json)](https://snyk.io/test/github/thiagobustamante/typescript-rest-swagger?targetFile=package.json)\n\n# Swagger for Typescript-rest\nThis is a tool to generate swagger files from a [typescript-rest](https://github.com/thiagobustamante/typescript-rest) project.\n\n**Table of Contents** \n\n- [Swagger for Typescript-rest](#swagger-for-typescript-rest)\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [Swagger Decorators](#swagger-decorators)\n      - [@Response](#response)\n      - [@Example](#example)\n      - [@Tags](#tags)\n      - [@Consumes](#consumes)\n      - [@Produces](#produces)\n      - [@Hidden](#hidden)\n      - [@IsInt, @IsLong, @IsFloat, @IsDouble](#isint-islong-isfloat-isdouble)\n    - [SwaggerConfig.json](#swaggerconfigjson)\n\n## Installation\n\n```bash\nnpm install typescript-rest-swagger -g\n```\n\n## Usage\n\n```bash\nswaggerGen -c ./swaggerConfig.json\nswaggerGen -c ./swaggerConfig.js #.js files are also allowed as config files\nswaggerGen -c ./swaggerConfig.json -t # load {cwd}/tsconfig.json\nswaggerGen -c ./swaggerConfig.json -p ./tsconfig.json # load custom tsconfig.json\n```\n\nWhere the [swaggerConfig.json](#swaggerconfigjson) file, contains settings about the swagger generation. For example:\n\n```json\n{\n    \"swagger\": {\n        \"outputDirectory\": \"./dist\",\n        \"entryFile\": \"./tests/data/apis.ts\"\n    }\n}\n```\n\nWhere the [tsconfig.json](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) file contains compilerOptions. For example:\n\n```json\n{\n    \"compilerOptions\": {\n        \"baseUrl\": \".\",\n        \"paths\": {\n            \"@/*\": [\"src/*\"]\n        }\n    }\n}\n```\n\nFor example above options are required for `swaggerGen` to understand relative imports like `import something from '@/something'`.\n\n### Swagger Decorators\n\nThe documentation will be generated consulting all [typescript-rest](https://github.com/thiagobustamante/typescript-rest) decorators present on your code.\nHowever, there are some additional informations that can be provided, only with documentation purposes, through some other decorators present into this library.\n\nSome examples:\n\n```typescript\nimport {Path, Accept, GET} from 'typescript-rest';\nimport {Tags} from 'typescript-rest-swagger';\n\n@Path('mypath')\nexport class MyService {\n    @GET\n    @Tags('adminMethod', 'otheTag')\n    @Accept('text/html')\n    test( ): string {\n        return 'OK';\n    }\n\n    @GET\n    @Path('secondpath')\n    test2( @QueryParam('testParam')test?: string ): Person {\n        return {name: 'OK'};\n    }\n}\n```\n\nIt is also important to observe that all JsDoc provided on your methods, classes, and parameters is outputed into the generated swagger file:\n\n```typescript\n@Accept('text/plain')\n@Path('mypath')\nexport class MyService {\n    /**\n     * This description will be used to describe the get operation of path '/mypath' on the generated swagger\n     * @param test And this will describe the parameter test of this same operation\n     */\n    @GET\n    @Path('secondpath')\n    test2( @QueryParam('testParam')test?: string ): Person {\n        return {name: 'OK'};\n    }\n}\n```\n\nThese are the available swagger decorators, provided by typescript-rest-swagger:\n\n#### @Response\n\nA decorator to document the responses that a given service method can return. It is used to generate documentation for the REST service.\n\n```typescript\ninterface MyError {\n   message: string\n}\n\n@Path('people')\nclass PeopleService {\n  @Response\u003cstring\u003e(200, 'Retrieve a list of people.')\n  @Response\u003cMyError\u003e(401, 'The user is unauthorized.', {message: 'The user is not authorized to access this operation.'})\n  @GET\n  getPeople(@Param('name') name: string) {\n     // ...\n  }\n}\n```\n\nA Default response is already created in swagger documentation from the method return analisys. So any response declared\nthrough this decorator is an additional response created.\n\n#### @Example\n\nUsed to provide an example of method return to be added into the method response section of the generated documentation for this method.\n\n```typescript\n@Path('people')\nclass PeopleService {\n  @Example\u003cArray\u003cPerson\u003e\u003e([{\n    name: 'Joe'\n  }])\n  @GET\n  getPeople(@Param('name') name: string): Person[] {\n     // ...\n  }\n}\n```\n\n#### @Tags\n\nAdd tags for a given method on generated swagger documentation.\n\n```typescript\n@Path('people')\nclass PeopleService {\n  @Tags('adiministrative', 'department1')\n  @GET\n  getPeople(@Param('name') name: string) {\n     // ...\n  }\n}\n```\n\n\n#### @Consumes \n\nDocument the consumes property in generated swagger docs\n\n```typescript\n@Path('people')\n@Consumes('text/html')\nclass PeopleService {\n  @PUT\n  createPeople(@Param('name') name: string, people: People) {\n     // ...\n  }\n}\n```\n\n#### @Produces \n\nDocument the produces property in generated swagger docs\n\n```typescript\n@Path('people')\n@Produces('text/html')\nclass PeopleService {\n  @GET\n  getPeople(@Param('name') name: string) {\n     // ...\n  }\n}\n```\n\nA Default produces is already created in swagger documentation from the method return analisys. \nYou can use this decorator to override this default produces.\n\n#### @Hidden \n\nAllow to hide some APIs from swagger docs (ex: test or dev APIs, etc ...).\nThis decorator can be applied for the whole class or only a single method\n\n```typescript\n@Path('people')\n@Hidden()\nclass PeopleService {\n  @GET\n  getPeople(@Param('name') name: string) {\n     // ...\n  }\n}\n```\n\n#### @IsInt, @IsLong, @IsFloat, @IsDouble\n\nDocument the type of a `number` property or parameter in generated swagger docs.\nIf no decorator is present, the `number` type defaults to `double` format.\n\n```typescript\nclass Person {\n    @IsInt id: number;\n}\n\n@Path('people')\nclass PeopleService {\n    @Path(':id')\n    @GET\n    getById(@PathParam('id') @IsLong id: number) {\n        // ...\n    }\n}\n```\n\nBecause decorators don't work on type and interface properties, this can also be specified as a JSDoc tag.\n\n```typescript\ninterface Person {\n    /**\n     * The person's id\n     * @IsInt\n     */\n    id: number;\n}\n```\n\n\n### SwaggerConfig.json \n\nThe swagger config file supports the following properties: \n\nProperty | Type | Description\n-------- | ---- | -----------\nbasePath | string | Base API path; e.g. the 'v1' in https://myapi.com/v1\nconsumes | [string] | Default consumes property for the entire API\ndescription | string | API description; defaults to npm package description\nentryFile | string or string[] | The entry point to your API (it is possible to use glob patters)\noutputFormat | 'Swagger_2' or 'OpenApi_3' | Inform if the generated spec will be in swagger 2.0 format or i open api 3.0\nhost | string | The hostname to be informed in the generated swagger file\nlicense | string | API license number; defaults to npm package license\nname | string | API name; defaults to npm package name\noutputDirectory | string | Where to write the generated swagger file\nproduces | [string] | Default produces property for the entire API\nversion | string | API version number; defaults to npm package version\nyaml | boolean | Generates the output also as an yaml file \nspec | any | Extend generated swagger spec with this object. Note that generated properties will always take precedence over what get specified here\nsecurityDefinitions | *SecurityDefinition | Security Definitions Object. A declaration of the security schemes available to be used in the specification. This does not enforce the security schemes on the operations and only serves to provide the relevant details for each scheme.\ncollectionFormat | string | Default collectionFormat property for the entire API. Possible values are `csv`, `ssv`, `tsv`, `pipes`, `multi`. If not specified, Swagger defaults to `csv`.\n\n\nWhere the SecurityDefinition contract is defined as:\n```typescript \n{\n    [name: string]: {\n        type: string;\n        name?: string;\n        authorizationUrl?: string;\n        tokenUrl?: string;\n        flow?: string;\n        in?: string;\n        scopes?: { [scopeName: string]: string; }\n    }\n}\n```\n\nSee an example:\n```json\n{\n    \"swagger\": {\n        \"outputDirectory\": \"./dist\",\n        \"entryFile\": \"./controllers/*.ts\",\n        \"outputFormat\": \"openapi_3\",\n        \"host\": \"localhost:3000\",\n        \"version\": \"1.0\",\n        \"name\": \"Typescript-rest Test API\",\n        \"description\": \"a description\",\n        \"license\": \"MIT\",\n        \"basePath\": \"/v1\",\n        \"securityDefinitions\": {\n            \"api_key\": {\n                \"type\": \"apiKey\",\n                \"name\": \"access_token\",\n                \"in\": \"query\"\n            }\n        },\n        \"ignore\": [\n          \"**/node_modules/**\"\n        ]\n    }\n}\n```\n\nor in yaml format:\nSee an example:\n\n```yaml\nswagger:\n  outputDirectory: ./dist\n  entryFile: \n    - ./controllers/*.ts\n  outputFormat: openapi_3\n  host: localhost:3000\n  version: 1.0\n  name: Typescript-rest Test API\n  description: A description\n  license: MIT\n  basePath: /v1\n  securityDefinitions:\n    api_key:\n      type: apiKey\n      name: access_token\n      in: query\n  ignore:\n    - /node_modules/**    \n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthiagobustamante%2Ftypescript-rest-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthiagobustamante%2Ftypescript-rest-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthiagobustamante%2Ftypescript-rest-swagger/lists"}