Skip to content

Commit b78e718

Browse files
MrBartusekMrBartusek
committed
Add swagger docs to most controlelrs
1 parent f7e2007 commit b78e718

File tree

9 files changed

+47
-11
lines changed

9 files changed

+47
-11
lines changed

‎apps/api/src/demo/demo.controller.ts

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
import { Controller, Post } from '@nestjs/common';
2-
import { ApiTags } from '@nestjs/swagger';
2+
import { ApiExcludeController, ApiHideProperty, ApiOperation, ApiTags } from '@nestjs/swagger';
33
import { PrivateUserDto } from 'shared-types';
44
import { User } from '../models/users/schemas/user.schema';
55
import { DemoService } from './demo.service';
66

7-
@ApiTags('demo')
87
@Controller('demo')
8+
@ApiTags('demo')
9+
@ApiExcludeController()
910
export class DemoController {
1011
constructor(private readonly demoService: DemoService) {}
1112

‎apps/api/src/images/images.controller.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { Controller, Get, Header, NotFoundException, Param, Res } from '@nestjs/common';
2-
import { ApiTags } from '@nestjs/swagger';
2+
import { ApiOperation, ApiProduces, ApiTags } from '@nestjs/swagger';
33
import { Response } from 'express';
44
import { createReadStream } from 'node:fs';
55
import { join } from 'node:path';
@@ -15,6 +15,7 @@ export class ImagesController {
1515

1616
@Get('default')
1717
@Header('Cache-Control', `public, max-age=${CACHE_TIME}`)
18+
@ApiOperation({ summary: 'Get default image' })
1819
getDefault(@Res() res: Response) {
1920
const assetsFolder = join(__dirname, '../..', 'src/assets');
2021
const file = createReadStream(join(assetsFolder, 'default.png'));
@@ -23,6 +24,7 @@ export class ImagesController {
2324

2425
@Get(':key')
2526
@Header('Cache-Control', `public, max-age=${CACHE_TIME}`)
27+
@ApiOperation({ summary: "Get a image by it's key" })
2628
async getByKey(@Param('key') key: string, @Res() response: Response) {
2729
const object = await this.imagesService.getObject(key);
2830
if (!object) {

‎apps/api/src/main.ts

+4-1
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,10 @@ export function configureNestApp(app: NestExpressApplication): void {
4444
async function setupSwagger(app: NestExpressApplication) {
4545
const config = new DocumentBuilder()
4646
.setTitle('StockedUp API')
47-
.setDescription('StockedUp API documentation')
47+
.setDescription(
48+
'StockedUp official API documentation! ' +
49+
'API keys are coming: [#61](https://github.com/MrBartusek/stocked-up/issues/61)',
50+
)
4851
.setVersion('1.0')
4952
.build();
5053
const document = SwaggerModule.createDocument(app, config);

‎apps/api/src/models/inventory/inventory.controller.ts

+7-2
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ import {
1212
Query,
1313
UseGuards,
1414
} from '@nestjs/common';
15-
import { ApiTags } from '@nestjs/swagger';
15+
import { ApiOperation, ApiTags } from '@nestjs/swagger';
1616
import { Types } from 'mongoose';
1717
import { BasicInventoryItemDto, InventoryItemDto, PageDto } from 'shared-types';
1818
import { AuthenticatedGuard } from '../../auth/guards/authenticated.guard';
@@ -35,7 +35,7 @@ export class InventoryController {
3535
constructor(private readonly inventoryService: InventoryService) {}
3636

3737
@Post()
38-
@HttpCode(201)
38+
@ApiOperation({ summary: 'Create new inventory item' })
3939
async create(@Body(SecurityValidationPipe) dto: CreateInventoryItemDto) {
4040
const warehouseId = new Types.ObjectId(dto.warehouseId);
4141
const productId = new Types.ObjectId(dto.productId);
@@ -52,6 +52,7 @@ export class InventoryController {
5252

5353
@Put(':id')
5454
@HttpCode(200)
55+
@ApiOperation({ summary: 'Update inventory item by id' })
5556
async update(
5657
@Param('id', ParseObjectIdPipe) id: Types.ObjectId,
5758
@Body(SecurityValidationPipe) dto: UpdateInventoryItemDto,
@@ -61,11 +62,13 @@ export class InventoryController {
6162

6263
@Delete(':id')
6364
@HttpCode(200)
65+
@ApiOperation({ summary: 'Delete inventory item by id' })
6466
async delete(@Param('id', ParseObjectIdPipe, HasInventoryAccessPipe) id: Types.ObjectId) {
6567
await this.inventoryService.delete(id);
6668
}
6769

6870
@Get('by-product')
71+
@ApiOperation({ summary: 'Get inventory item by warehouse id and product id' })
6972
async findByProduct(
7073
@Query('warehouseId', ParseObjectIdPipe, HasWarehouseAccessPipe) warehouseId: Types.ObjectId,
7174
@Query('productId', ParseObjectIdPipe, HasProductAccessPipe) productId: Types.ObjectId,
@@ -80,6 +83,7 @@ export class InventoryController {
8083
}
8184

8285
@Get('by-warehouse/:id')
86+
@ApiOperation({ summary: 'List inventory items in warehouse' })
8387
async list(
8488
@Param('id', ParseObjectIdPipe, HasWarehouseAccessPipe) warehouseId: Types.ObjectId,
8589
@Query(
@@ -100,6 +104,7 @@ export class InventoryController {
100104
}
101105

102106
@Get(':id')
107+
@ApiOperation({ summary: 'Get inventory item by id' })
103108
async findOne(
104109
@Param('id', ParseObjectIdPipe, HasInventoryAccessPipe) id: Types.ObjectId,
105110
): Promise<InventoryItemDto> {

‎apps/api/src/models/organizations/organizations.controller.ts

+7-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ import {
1212
Req,
1313
UseGuards,
1414
} from '@nestjs/common';
15-
import { ApiTags } from '@nestjs/swagger';
15+
import { ApiOperation, ApiTags } from '@nestjs/swagger';
1616
import { Request } from 'express';
1717
import { Types } from 'mongoose';
1818
import { OrganizationDto, OrganizationSecurityRole, PageDto } from 'shared-types';
@@ -44,6 +44,7 @@ export class OrganizationsController {
4444
) {}
4545

4646
@Post()
47+
@ApiOperation({ summary: 'Create new organization' })
4748
async create(
4849
@Body() createOrganizationDto: CreateOrganizationDto,
4950
@Req() request: Request,
@@ -64,6 +65,7 @@ export class OrganizationsController {
6465
}
6566

6667
@Get()
68+
@ApiOperation({ summary: 'List organizations that authenticated user has access to' })
6769
async list(
6870
@Req() request: Request,
6971
@Query(
@@ -85,6 +87,7 @@ export class OrganizationsController {
8587
}
8688

8789
@Put(':id')
90+
@ApiOperation({ summary: 'Update a organization by id' })
8891
async update(
8992
@Param('id', ParseObjectIdPipe, HasOrganizationAccessPipe) id: Types.ObjectId,
9093
@Body() dto: UpdateOrganizationDto,
@@ -97,6 +100,7 @@ export class OrganizationsController {
97100
}
98101

99102
@Delete(':id')
103+
@ApiOperation({ summary: 'Delete a organization by id' })
100104
async delete(
101105
@Param('id', ParseObjectIdPipe, HasOwnerAccessPipe) id: Types.ObjectId,
102106
): Promise<OrganizationDto> {
@@ -108,6 +112,7 @@ export class OrganizationsController {
108112
}
109113

110114
@Get(':id')
115+
@ApiOperation({ summary: 'Get a organization by id' })
111116
async findById(
112117
@Param('id', ParseObjectIdPipe, HasOrganizationAccessPipe) id: Types.ObjectId,
113118
): Promise<OrganizationDto> {
@@ -116,6 +121,7 @@ export class OrganizationsController {
116121
}
117122

118123
@Patch(':id/settings')
124+
@ApiOperation({ summary: 'Update organization settings by id' })
119125
async updateSettings(
120126
@Param('id', ParseObjectIdPipe, HasOrganizationAccessPipe) id: Types.ObjectId,
121127
@Body() patchOrganizationSettingsDto: PatchOrganizationSettingsDto,

‎apps/api/src/models/products/products.controller.ts

+6-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import {
1010
Query,
1111
UseGuards,
1212
} from '@nestjs/common';
13-
import { ApiTags } from '@nestjs/swagger';
13+
import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
1414
import { Types } from 'mongoose';
1515
import { PageDto, ProductDto } from 'shared-types';
1616
import { AuthenticatedGuard } from '../../auth/guards/authenticated.guard';
@@ -33,13 +33,15 @@ export class ProductsController {
3333
constructor(private readonly productsService: ProductsService) {}
3434

3535
@Post()
36+
@ApiOperation({ summary: 'Create new product definition' })
3637
async create(@Body(SecurityValidationPipe) dto: CreateProductDto): Promise<ProductDto> {
3738
const product = await this.productsService.create(dto);
3839

3940
return Product.toDto(product);
4041
}
4142

4243
@Get(':id')
44+
@ApiOperation({ summary: 'Get a product by id' })
4345
async findOne(
4446
@Param('id', ParseObjectIdPipe, HasProductAccessPipe) id: Types.ObjectId,
4547
): Promise<ProductDto> {
@@ -48,6 +50,7 @@ export class ProductsController {
4850
}
4951

5052
@Get('list/:id')
53+
@ApiOperation({ summary: 'List all products in organization' })
5154
async list(
5255
@Param('id', ParseObjectIdPipe, HasOrganizationAccessPipe) orgId: Types.ObjectId,
5356
@Query(
@@ -67,6 +70,7 @@ export class ProductsController {
6770
}
6871

6972
@Put(':id')
73+
@ApiOperation({ summary: 'Update a product by id' })
7074
async update(
7175
@Param('id', ParseObjectIdPipe, HasProductAccessPipe) id: Types.ObjectId,
7276
@Body(SecurityValidationPipe) dto: UpdateProductDto,
@@ -76,6 +80,7 @@ export class ProductsController {
7680
}
7781

7882
@Delete(':id')
83+
@ApiOperation({ summary: 'Delete product by id' })
7984
async delete(
8085
@Param('id', ParseObjectIdPipe, HasProductAccessPipe) id: Types.ObjectId,
8186
): Promise<ProductDto> {

‎apps/api/src/models/users/users.controller.ts

+4-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import {
1010
Req,
1111
UseGuards,
1212
} from '@nestjs/common';
13-
import { ApiTags } from '@nestjs/swagger';
13+
import { ApiOperation, ApiTags } from '@nestjs/swagger';
1414
import { Request } from 'express';
1515
import { Types } from 'mongoose';
1616
import { PrivateUserDto, UserDto } from 'shared-types';
@@ -27,6 +27,7 @@ export class UsersController {
2727
constructor(private readonly usersService: UsersService) {}
2828

2929
@Get('me')
30+
@ApiOperation({ summary: 'Get authenticated user data' })
3031
async findAuthenticated(@Req() request: Request): Promise<PrivateUserDto> {
3132
const userId = new Types.ObjectId(request.user.id);
3233
const user = await this.usersService.findById(userId);
@@ -39,6 +40,7 @@ export class UsersController {
3940
}
4041

4142
@Get(':id')
43+
@ApiOperation({ summary: 'Get user data by id' })
4244
async findOne(@Param('id', ParseObjectIdPipe) id: Types.ObjectId): Promise<UserDto> {
4345
const user = await this.usersService.findById(id);
4446

@@ -50,6 +52,7 @@ export class UsersController {
5052
}
5153

5254
@Put()
55+
@ApiOperation({ summary: 'Update authenticated user profile' })
5356
async updateProfile(@Req() request: Request, @Body() dto: UpdateUserDto) {
5457
const userId = new Types.ObjectId(request.user.id);
5558

‎apps/api/src/models/warehouses/warehouses.controller.ts

+6-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import {
1010
Put,
1111
Query,
1212
} from '@nestjs/common';
13-
import { ApiTags } from '@nestjs/swagger';
13+
import { ApiOperation, ApiTags } from '@nestjs/swagger';
1414
import { Types } from 'mongoose';
1515
import { PageDto, WarehouseDto } from 'shared-types';
1616
import { PageQueryDto } from '../../dto/page-query.dto';
@@ -30,13 +30,15 @@ export class WarehousesController {
3030
constructor(private readonly warehousesService: WarehousesService) {}
3131

3232
@Post()
33+
@ApiOperation({ summary: 'Create new warehouse in organization' })
3334
async create(@Body(SecurityValidationPipe) dto: CreateWarehouseInOrgDto): Promise<WarehouseDto> {
3435
const orgId = new Types.ObjectId(dto.organizationId);
3536
const warehouse = await this.warehousesService.create(orgId, dto.warehouse);
3637
return Warehouse.toDto(warehouse);
3738
}
3839

3940
@Get(':id')
41+
@ApiOperation({ summary: 'Get warehouse by id' })
4042
async findOne(
4143
@Param('id', ParseObjectIdPipe, HasWarehouseAccessPipe) id: Types.ObjectId,
4244
): Promise<WarehouseDto> {
@@ -48,6 +50,7 @@ export class WarehousesController {
4850
}
4951

5052
@Get('list/:id')
53+
@ApiOperation({ summary: 'List warehouses in organization' })
5154
async list(
5255
@Param('id', ParseObjectIdPipe, HasOrganizationAccessPipe) orgId: Types.ObjectId,
5356
@Query(
@@ -67,6 +70,7 @@ export class WarehousesController {
6770
}
6871

6972
@Put(':id')
73+
@ApiOperation({ summary: 'Update warehouses by id' })
7074
async update(
7175
@Param('id', ParseObjectIdPipe, HasWarehouseAccessPipe) id: Types.ObjectId,
7276
@Body(SecurityValidationPipe) dto: UpdateWarehouseDto,
@@ -79,6 +83,7 @@ export class WarehousesController {
7983
}
8084

8185
@Delete(':id')
86+
@ApiOperation({ summary: 'Delete warehouses by id' })
8287
async delete(
8388
@Param('id', ParseObjectIdPipe, HasWarehouseAccessPipe) id: Types.ObjectId,
8489
): Promise<WarehouseDto> {

‎apps/api/src/security/security.controller.ts

+7-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ import {
1313
Req,
1414
UseGuards,
1515
} from '@nestjs/common';
16-
import { ApiTags } from '@nestjs/swagger';
16+
import { ApiOperation, ApiTags } from '@nestjs/swagger';
1717
import { Request } from 'express';
1818
import { Types } from 'mongoose';
1919
import { OrganizationSecurityRole, PageDto, SecurityRuleDto } from 'shared-types';
@@ -40,6 +40,7 @@ export class SecurityController {
4040

4141
@Post()
4242
@UseGuards(ConfirmedGuard)
43+
@ApiOperation({ summary: 'Create new security rule' })
4344
async create(@Body(SecurityValidationPipe) dto: CreateSecurityRuleDto): Promise<any> {
4445
const org = new Types.ObjectId(dto.organization);
4546

@@ -57,6 +58,7 @@ export class SecurityController {
5758
}
5859

5960
@Put()
61+
@ApiOperation({ summary: 'Update a security rule by id' })
6062
async update(
6163
@Req() request: Request,
6264
@Body(SecurityValidationPipe) dto: UpdateSecurityRuleDto,
@@ -74,6 +76,7 @@ export class SecurityController {
7476
}
7577

7678
@Delete()
79+
@ApiOperation({ summary: 'Delete a security rule by id' })
7780
async delete(
7881
@Req() request: Request,
7982
@Body(SecurityValidationPipe) dto: DeleteSecurityRuleDto,
@@ -91,6 +94,7 @@ export class SecurityController {
9194
}
9295

9396
@Delete(':org/leave')
97+
@ApiOperation({ summary: 'Leave organization by id' })
9498
async leave(
9599
@Req() request: Request,
96100
@Param('org', ParseObjectIdPipe, HasOrganizationAccessPipe) org: Types.ObjectId,
@@ -111,6 +115,7 @@ export class SecurityController {
111115
}
112116

113117
@Get(':id')
118+
@ApiOperation({ summary: 'List organization security rules' })
114119
async listRules(
115120
@Param('id', ParseObjectIdPipe, HasOrganizationAccessPipe) organization: Types.ObjectId,
116121
@Query(
@@ -125,6 +130,7 @@ export class SecurityController {
125130
}
126131

127132
@Get(':org/me')
133+
@ApiOperation({ summary: 'Get security rule of authenticated user' })
128134
async getMeRule(
129135
@Req() request: Request,
130136
@Param('org', ParseObjectIdPipe, HasOrganizationAccessPipe) organization: Types.ObjectId,

0 commit comments

Comments
 (0)