{"id":22880960,"url":"https://github.com/beermoneydev/nest-openapi-tools","last_synced_at":"2025-04-09T18:18:05.767Z","repository":{"id":38173418,"uuid":"281393857","full_name":"BeerMoneyDev/nest-openapi-tools","owner":"BeerMoneyDev","description":"A collection of tools to make building and deploying AWS serverless Nest applications AWESOME.","archived":false,"fork":false,"pushed_at":"2025-03-28T01:44:10.000Z","size":2637,"stargazers_count":12,"open_issues_count":11,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-09T18:17:58.963Z","etag":null,"topics":[],"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/BeerMoneyDev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2020-07-21T12:37:42.000Z","updated_at":"2025-02-14T14:28:19.000Z","dependencies_parsed_at":"2024-09-26T19:24:50.792Z","dependency_job_id":"63174c71-a8b6-4ab6-a666-18efd7fd0732","html_url":"https://github.com/BeerMoneyDev/nest-openapi-tools","commit_stats":{"total_commits":59,"total_committers":11,"mean_commits":5.363636363636363,"dds":0.6949152542372881,"last_synced_commit":"bf146676bd0631234a0419f14b6d678a2e5b5f89"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeerMoneyDev%2Fnest-openapi-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeerMoneyDev%2Fnest-openapi-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeerMoneyDev%2Fnest-openapi-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeerMoneyDev%2Fnest-openapi-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BeerMoneyDev","download_url":"https://codeload.github.com/BeerMoneyDev/nest-openapi-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248085326,"owners_count":21045139,"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":[],"created_at":"2024-12-13T17:28:48.549Z","updated_at":"2025-04-09T18:18:05.746Z","avatar_url":"https://github.com/BeerMoneyDev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003enest-openapi-tools\u003c/h1\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://beermoneydev-assets.s3.amazonaws.com/nest-openapi-tools-logo.png\" /\u003e\n\u003c/div\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cstrong\u003eEasily integrate Swagger/OpenAPI with NestJS APIs.\u003c/strong\u003e\n\u003c/div\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://www.npmjs.com/package/nest-openapi-tools\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/nest-openapi-tools.svg\" alt=\"NPM Version\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://www.npmjs.com/package/nest-openapi-tools\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/nest-openapi-tools.svg\" alt=\"Package License\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://www.npmjs.com/package/nest-openapi-tools\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/nest-openapi-tools.svg\" alt=\"NPM Downloads\" /\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n# Installation\n\n```bash\nnpm install --save nest-openapi-tools @nestjs/swagger swagger-ui-express\n```\n\n# About\n\nThis library's goal is to make it as easy as possible to use NestJS with Swagger, also known as OpenAPI. NestJS's Swagger package does not currently generate specification file - rather, it generates the web server with the specification.\n\nThis package leverages that tooling to generate a YAML or JSON specification file as well as `@openapitools/openapi-generator-cli` to then generate a client. By using this as part of our development experience, we can build our APIs with NestJS's `npm run start:dev` running and have a new, fully-setup API client ready to go for our consuming layer (whether this is a SPA app or another API service).\n\n# Usage\n\n## Setting up API Definitions in NestJS\n\nThe [NestJS OpenAPI docs for @NestJS/Swagger](https://docs.nestjs.com/openapi/introduction) are a fantastic guide to defining your API in code. There are two routes:\n\n1. Using the [CLI Plugin](https://docs.nestjs.com/openapi/cli-plugin). This is recommended as it is very hands-off and easy-to-use. However, it is a bit of a \"magic\" solution - this can sometimes prove frustrating.\n2. Use decorators for [operations](https://docs.nestjs.com/openapi/operations) and [types](https://docs.nestjs.com/openapi/types-and-parameters). This is more hands-on but is concise in what is expected to be produced.\n\nThese must be complete in order for Nest OpenAPI Tools to function - this package leverages the NestJS Swagger library to generate the server and specification file. \n\n## OpenApiNestFactory\n\nThe OpenApiNestFactory simplifies the process of:\n\n1. Generating an OpenAPI file from a NestJS API.\n2. Generating a client project (i.e. an Axios client or an Angular client module).\n3. Starting up the OpenAPI documentation web server.\n\n### How to use\n\nTo leverage this functionality, add a call to `OpenApiNestFactory.configure()` call as demonstrated below.\n\n```ts\n// main.ts - BEFORE\nimport { NestFactory } from '@nestjs/core';\nimport { AppModule } from './app.module';\n\nasync function bootstrap() {\n  const app = await NestFactory.create(AppModule);\n  await app.listen(3000);\n}\nbootstrap();\n```\n\n```ts\n// main.ts - AFTER\nimport { NestFactory } from '@nestjs/core';\nimport { AppModule } from './app.module';\nimport { OpenApiNestFactory } from 'nest-openapi-tools';\n\nasync function bootstrap() {\n  const app = await NestFactory.create(AppModule);\n\n  await OpenApiNestFactory.configure(\n    app, \n    new DocumentBuilder().setTitle('My API'),\n  );\n\n  await app.listen(3000);\n}\nbootstrap();\n```\n\nThis falls back to all defaults provided by Nest OpenAPI Tools to:\n\n* enable the documentation web server at http://localhost:3000/api-docs\n* generate the OpenAPI document at `./openapi.yaml`\n* generate a TypeScript Axios HTTP client at `../my-api-client`.\n\nNote that all of these values can be changed as demonstrated in the section below.\n\n### OpenApiNestFactory configuration\n\nThese are the default values when no options are passed in to OpenApiNestFactory. To override these, simply use the configuration object (the third argument in the `configure()` call).\n\n```ts\n// main.ts\nimport { NestFactory } from '@nestjs/core';\nimport { AppModule } from './app.module';\nimport { OpenApiNestFactory } from 'nest-openapi-tools';\n\nasync function bootstrap() {\n  const app = await NestFactory.create(AppModule);\n\n  await OpenApiNestFactory.configure(app, \n    new DocumentBuilder()\n      .setTitle('My API')\n      .setDescription('An API to do awesome things')\n      .addBearerAuth(),\n    {\n      webServerOptions: {\n        enabled: true,\n        path: 'api-docs',\n      },\n      fileGeneratorOptions: {\n        enabled: true,\n        outputFilePath: './openapi.yaml',  // or ./openapi.json\n      },\n      clientGeneratorOptions: {\n        enabled: true,\n        type: 'typescript-axios',\n        outputFolderPath: '../typescript-api-client/src',\n        additionalProperties:\n          'apiPackage=clients,modelPackage=models,withoutPrefixEnums=true,withSeparateModelsAndApi=true',\n        openApiFilePath: './openapi.yaml', // or ./openapi.json\n        skipValidation: true, // optional, false by default\n      },\n    }, {\n    operationIdFactory: (c: string, method: string) =\u003e method,\n  });\n\n  await app.listen(3000);\n}\nbootstrap();\n```\n\n***NOTICE!* File generation and client generation should be disabled in production as they are costly to startup time.**\n\n### Client Generator Options\n\nThis project leverages the [OpenAPITools/openapi-generator](https://github.com/OpenAPITools/openapi-generator) project via the npm package, `@openapitools/openapi-generator-cli` which is required to be installed globally. Accordingly, any client generators and configuration supported by this project are usable via Nest OpenAPI Tools.\n\n#### Client Generator Classes\n\nTo help with getting started, Nest OpenAPI Tools provides some classes with helpful defaults.\n\n**AxiosClientGeneratorOptions**\n\n* type = 'typescript-axios';\n* outputFolderPath = '../typescript-api-client/src';\n* additionalProperties = 'apiPackage=clients,modelPackage=models,withoutPrefixEnums=true,withSeparateModelsAndApi=true';\n* openApiFilePath = './openapi.yaml';\n\n# Stay in touch\n\nAuthor - Kerry Ritter, BeerMoneyDev\n\nWebsite - https://www.kerryritter.com/, https://www.beermoney.dev/","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeermoneydev%2Fnest-openapi-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeermoneydev%2Fnest-openapi-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeermoneydev%2Fnest-openapi-tools/lists"}