CLI Plugin and Migration Guide Using NestJs and OpenAPI
Simplifying Innovation: NestJS and OpenAPI - Seamless Integration with CLI Plugin and Migration Excellence
In a previous blog post, we explored the powerful combination of MappingTypes and Decorators with NestJS framework
A CLI plugin is like an extra tool that you can add to your computer's command box. It gives you more powers to do different things, like adding new tricks to your favorite magic wand. So, if you use a command line to control your computer and want it to do more things, you can add these plugins to help you without making any big changes. CLI plugin refers to an additional piece of software that you can add to the Command Line Interface(CLI) this tool enhances the functionality
Command Line Interface (CLI)
CLI is a way of interacting with a computer program or system through text-based commands. It allows users to perform various tasks by typing commands directly into a terminal or command prompt.
CLI Plugin
CLI is an additional piece of software that you can integrate with the main CIL tool.
Plugins offer additional functionalities, features, or commands for CLI tools, simplifying specific task performance without requiring coding
For example, imagine you have a CLI tool that helps you manage and deploy websites. However, you want to add a feature that optimizes images automatically during deployment.
Instead of modifying the main CLI tool's code, you can create a separate "image optimization" CLI users can install and use this plugin in addition to the main CLI to handle image-related tasks without needing to learn a new set of commands or tools.
NestJS Project with Typescript Step-by-Step Guidelines.
Step 1: Install the Nest CLI globally
npm install -g @nestjs/cli
Step 2: Create a new NestJs Project using CLI
nest new project-name
Step 3: Use CLI to generate modules, controllers, and services.
nest generate module module-name
nest genrate controller controller-name
Step 4: Start Your NestJS Application
npm run start
Other Features
A global prefix is a special word used at the beginning of a website address, indicating a specific region. It is added to all website addresses to ensure they start with that word. Routes are the paths users take when navigating a city. SetGlobalPrefix() sets the global prefix for all routes on a website. IgnoreGlobalPrefix allows users to ignore the special word at the beginning of a URL.
const document = SwaggerModule.createDocument(app, opitions, {
ignoreGlobalPrefix:true,
});
Global Parameters are essential pieces of information to be attached to various parts of your website. Each piece has a specific name and description. DocumentBuilder is a tool that creates a document for your website, resembling a magic pen. Parameter definitions are automatically applied to every part of your website, making it a valuable tool for managing and organizing information.
const options = new DocumentBuilder().addGlobalParameters({
name:'byteScrum';
in:'header',
});
Multiple Specifications
The SwaggerModule is a tool that helps create different sets of instructions for your website, resembling a magic book. It allows you to create different endpoints for each section, like separate shelves in a library.
The module approach involves organizing your website into sections, each with its own set of instructions. The createDocument() method allows you to create new instructions for a specific section, and the "extraOptions" and "include" properties allow you to add additional items.
Overall, the SwaggerModule provides a way to create separate guidebooks for different parts of your website, allowing you to create a comprehensive and user-friendly experience.
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';
import { CatsModule } from './cats/cats.module';
import { DogsModule } from './dogs/dogs.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
const options = new DocumentBuilder()
.setTitle('Cats example')
.setDescription('The cats API description')
.setVersion('1.0')
.addTag('cats')
.build();
const catDocument = SwaggerModule.createDocument(app, options, {
include: [CatsModule],
});
SwaggerModule.setup('api/cats', app, catDocument);
const secondOptions = new DocumentBuilder()
.setTitle('Dogs example')
.setDescription('The dogs API description')
.setVersion('1.0')
.addTag('dogs')
.build();
const dogDocument = SwaggerModule.createDocument(app, secondOptions, {
include: [DogsModule],
});
SwaggerModule.setup('api/dogs', app, dogDocument);
await app.listen(3000);
}
bootstrap();
Start Your NestJS Application
npm run start
Navigate Swagger UI
Navigate to localhost:3000/api/cats to see Swagger UI for cats
Navigate to localhost:3000/api/dogs to see Swagger UI for dogs
Migration Guide for NestJS and TypeScript:
@nest.js/swagger@3.* is the current version 4.0 for breaking/API
Breaking Changes in Decorators:
@ApiModelProperty is now @ApiProperty
@ApiImplicitQuery is now @ApiQuery
@ApiImplicitParam is now @ApiParam
@ApiImplicitBody is now @ApiBody
@ApiImplicitHeader is now @ApiHeader
@ApiOperation({ title: 'test' }) is now @ApiOperation({ summary: 'test' })
@ApiUseTags is now @ApiTags
Updated method Signatures:(DocumentBulider)
'addTag' - This function is used to insert tags into the created Swagger document.
'addBearerAuth' - Add a bearer authentication strategy to the created Swagger document using this method.
'addOAuth2' - Add an OAuth2 authentication strategy to the created Swagger document using this method.
'setContactEmail' is now 'set.Contact' - Set the contact information for the created Swagger document using this function.
'setHost' was deprecated - This method was deprecated. Use the 'addServer' method to configure the host.
'setSchemes' has been deprecated - This method is no longer available. Use the 'addServer' method instead, with suitable schemes such as 'addServer('http://')' or 'addServer('https://').
New Methods
addServer - This function is used to include a server in the created Swagger document.
addApiKey - Add an API key security specification to the created Swagger document using this function.
addBasicAuth - Use this method to add a security definition for basic authentication to the resulting Swagger document.
addSecurity - Add a custom security definition to the produced Swagger document using this function.
addSecurityRequirements - Add security requirements to the created Swagger document using this function.
When migrating your code, replace the old decorators with the new ones, update the DocumentBuilder methods, and add any new methods that are required. For further background and examples, see the NestJS documentation and the @nestjs/swagger documentation.
"we've had the pleasure of delving into the world of NestJS and OpenAPI integration throughout this series." Exploring the complexities of this confluence has been a fascinating experience. From the first steps of installing the CLI plugin until the last phases of seamless migration, every step has been an adventure.
The knowledge obtained while navigating the CLI plugin installation procedure has been essential. Understanding how these technologies interact and complement one another has opened up new avenues for creativity. Furthermore, the migration guide outlined a clear method for easily transitioning from prior versions, ensuring that the journey is as easy as possible. As we finish this series, we are reminded of the power of technological cooperation.
NestJS and OpenAPI together are not only efficient but also full of promise for innovative problem-solving and inventive applications. we are happy for the opportunity to be a part of this learning experience, and we forward to continuing researching as these technologies grow."
Thank you for reading our blogs. Our top priority is your success and satisfaction. We are ready to assist with any questions or additional help.
Warm regards,
ByteScrum Blog Team,