npm package: @nestgate/rest
Description: Elegant REST API decorators combining routing, validation, and documentation
Author: berkerozer
Latest version: 0.0.1

# @nestgate/rest

Elegant REST API decorators that combine routing, validation, and documentation in a single decorator.

## 🎯 Features

- **Composable Decorators** - Combine `@Get`, `@Post`, etc. with `@ApiResponse` and `@ApiOperation`
- **Auto-Documentation** - Swagger integration out of the box
- **Type-Safe** - Full TypeScript support
- **Clean Code** - Reduce boilerplate significantly

## 📦 Installation

```bash
npm install @nestgate/rest
# or
pnpm add @nestgate/rest
# or
yarn add @nestgate/rest
```

## 🚀 Quick Start

### Before NestGate

```typescript
import { Controller, Get, Post } from '@nestjs/common';
import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';

@Controller('users')
@ApiTags('Users')
export class UsersController {
  @Get()
  @ApiOperation({ summary: 'Get all users' })
  @ApiResponse({ status: 200, type: [UserDto] })
  async findAll() {
    // ...
  }

  @Post()
  @ApiOperation({ summary: 'Create a new user' })
  @ApiResponse({ status: 201, type: UserDto })
  async create() {
    // ...
  }
}
```

### With NestGate

```typescript
import { Controller } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';
import { ApiGet, ApiPost } from '@nestgate/rest';

@Controller('users')
@ApiTags('Users')
export class UsersController {
  @ApiGet('', UserDto, {
    summary: 'Get all users',
  })
  async findAll() {
    // ...
  }

  @ApiPost('', UserDto, {
    summary: 'Create a new user',
  })
  async create() {
    // ...
  }
}
```

## 📚 API Reference

### Available Decorators

- `@ApiGet(path?, model?, options?)` - Combines `@Get()`, `@ApiResponse()`, `@ApiOperation()`
- `@ApiPost(path?, model?, options?)` - Combines `@Post()`, `@ApiResponse()`, `@ApiOperation()`
- `@ApiPatch(path?, model?, options?)` - Combines `@Patch()`, `@ApiResponse()`, `@ApiOperation()`
- `@ApiPut(path?, model?, options?)` - Combines `@Put()`, `@ApiResponse()`, `@ApiOperation()`
- `@ApiDelete(path?, model?, options?)` - Combines `@Delete()`, `@ApiResponse()`, `@ApiOperation()`

### Parameters

#### `path` (optional)

- Type: `string`
- Default: `''`
- Description: The route path

#### `model` (optional)

- Type: `Type<any>`
- Description: The response model class for Swagger documentation

#### `options` (optional)

- Type: `ApiGateOptions`
- Properties:
  - `summary?: string` - API operation summary
  - `description?: string` - API operation description
  - `deprecated?: boolean` - Mark as deprecated

### Status Codes

- `@ApiGet` - Returns `200 OK`
- `@ApiPost` - Returns `201 Created`
- `@ApiPatch` - Returns `200 OK`
- `@ApiPut` - Returns `201 Created`
- `@ApiDelete` - Returns `200 OK` if model provided, `204 No Content` if not

## 💡 Examples

### Basic Usage

```typescript
import { ApiGet } from '@nestgate/rest';

@ApiGet('users', UserDto)
findAll() {
  return this.userService.findAll();
}
```

### With Options

```typescript
import { ApiGet } from '@nestgate/rest';

@ApiGet('users', UserDto, {
  summary: 'Get all users',
  description: 'Retrieves a paginated list of all users',
  deprecated: false
})
findAll() {
  return this.userService.findAll();
}
```

### With Path Parameters

```typescript
import { ApiGet } from '@nestgate/rest';

@ApiGet('users/:id', UserDto, {
  summary: 'Get user by ID'
})
findOne(@Param('id') id: string) {
  return this.userService.findOne(id);
}
```

### Delete Without Response Model

```typescript
import { ApiDelete } from '@nestgate/rest';

@ApiDelete('users/:id', undefined, {
  summary: 'Delete user'
})
// Returns 204 No Content
remove(@Param('id') id: string) {
  return this.userService.remove(id);
}
```

### Delete With Response Model

```typescript
import { ApiDelete } from '@nestgate/rest';

@ApiDelete('users/:id', UserDto, {
  summary: 'Delete user and return deleted data'
})
// Returns 200 OK with user data
remove(@Param('id') id: string) {
  return this.userService.remove(id);
}
```

## 🔗 Related Packages

- [@nestgate/validators](../validators) - Type-safe validation decorators
- [@nestgate/core](../core) - Core utilities

## 📝 License

MIT © [NestGate](https://nestgate.org)

## 🤝 Contributing

Contributions are welcome! Please see our [Contributing Guide](../../CONTRIBUTING.md).

## 💬 Support

- [Documentation](https://nestgate.org)
- [GitHub Issues](https://github.com/nestgate/nestgate/issues)
- [Discord](https://discord.gg/nestgate)