Skip to content

Commit 96567a5

Browse files
github-actions[bot]Marfuen
github-actions[bot]
and
Marfuen
authored
[dev] [Marfuen] mariano/fix-docs-2 (#1515)
* Enhance API documentation and response schemas - Added functionality to write OpenAPI documentation to a JSON file during development. - Updated response schemas across various controllers to use the new content format for better clarity and structure. - Improved error handling and response consistency for various endpoints, including organization, member, policy, and risk management. These changes improve the API's documentation and response handling, ensuring better usability and maintainability. * Refactor PeopleController and enhance OpenAPI documentation - Updated PeopleController to improve code readability by formatting and organizing imports and method parameters. - Added UserResponseDto schema to OpenAPI documentation for better clarity on user-related responses. - Enhanced PeopleResponseDto schema to include additional properties for improved response structure. These changes enhance the maintainability of the code and improve the API documentation for better usability. * Enhance Policies and Tasks Controllers with OpenAPI Documentation - Refactored import statements for better organization in PoliciesController and TasksController. - Added ApiExtraModels for PolicyResponseDto and TaskResponseDto to improve API documentation. - Updated OpenAPI JSON schema to include detailed definitions for PolicyResponseDto, TaskResponseDto, and AttachmentResponseDto, enhancing clarity and usability of the API responses. These changes improve the maintainability of the code and enrich the API documentation for better developer experience. --------- Co-authored-by: Mariano Fuentes <marfuen98@gmail.com>
1 parent ee36bc0 commit 96567a5

4 files changed

Lines changed: 497 additions & 62 deletions

File tree

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

Lines changed: 60 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,30 @@
1-
import {
2-
Controller,
3-
Get,
1+
import {
2+
Controller,
3+
Get,
44
Post,
55
Patch,
66
Delete,
77
Body,
88
Param,
9-
UseGuards
9+
UseGuards,
1010
} from '@nestjs/common';
1111
import {
1212
ApiBody,
13+
ApiExtraModels,
1314
ApiHeader,
1415
ApiOperation,
1516
ApiParam,
1617
ApiResponse,
1718
ApiSecurity,
1819
ApiTags,
1920
} from '@nestjs/swagger';
20-
import {
21-
AuthContext,
22-
OrganizationId,
23-
} from '../auth/auth-context.decorator';
21+
import { AuthContext, OrganizationId } from '../auth/auth-context.decorator';
2422
import { HybridAuthGuard } from '../auth/hybrid-auth.guard';
2523
import type { AuthContext as AuthContextType } from '../auth/types';
2624
import { CreatePeopleDto } from './dto/create-people.dto';
2725
import { UpdatePeopleDto } from './dto/update-people.dto';
2826
import { BulkCreatePeopleDto } from './dto/bulk-create-people.dto';
29-
import { PeopleResponseDto } from './dto/people-responses.dto';
27+
import { PeopleResponseDto, UserResponseDto } from './dto/people-responses.dto';
3028
import { PeopleService } from './people.service';
3129
import { GET_ALL_PEOPLE_RESPONSES } from './schemas/get-all-people.responses';
3230
import { CREATE_MEMBER_RESPONSES } from './schemas/create-member.responses';
@@ -39,6 +37,7 @@ import { PEOPLE_PARAMS } from './schemas/people-params';
3937
import { PEOPLE_BODIES } from './schemas/people-bodies';
4038

4139
@ApiTags('People')
40+
@ApiExtraModels(PeopleResponseDto, UserResponseDto)
4241
@Controller({ path: 'people', version: '1' })
4342
@UseGuards(HybridAuthGuard)
4443
@ApiSecurity('apikey')
@@ -61,18 +60,20 @@ export class PeopleController {
6160
@OrganizationId() organizationId: string,
6261
@AuthContext() authContext: AuthContextType,
6362
) {
64-
const people = await this.peopleService.findAllByOrganization(organizationId);
63+
const people =
64+
await this.peopleService.findAllByOrganization(organizationId);
6565

6666
return {
6767
data: people,
6868
count: people.length,
6969
authType: authContext.authType,
70-
...(authContext.userId && authContext.userEmail && {
71-
authenticatedUser: {
72-
id: authContext.userId,
73-
email: authContext.userEmail,
74-
},
75-
}),
70+
...(authContext.userId &&
71+
authContext.userEmail && {
72+
authenticatedUser: {
73+
id: authContext.userId,
74+
email: authContext.userEmail,
75+
},
76+
}),
7677
};
7778
}
7879

@@ -94,12 +95,13 @@ export class PeopleController {
9495
return {
9596
...member,
9697
authType: authContext.authType,
97-
...(authContext.userId && authContext.userEmail && {
98-
authenticatedUser: {
99-
id: authContext.userId,
100-
email: authContext.userEmail,
101-
},
102-
}),
98+
...(authContext.userId &&
99+
authContext.userEmail && {
100+
authenticatedUser: {
101+
id: authContext.userId,
102+
email: authContext.userEmail,
103+
},
104+
}),
103105
};
104106
}
105107

@@ -116,17 +118,21 @@ export class PeopleController {
116118
@OrganizationId() organizationId: string,
117119
@AuthContext() authContext: AuthContextType,
118120
) {
119-
const result = await this.peopleService.bulkCreate(organizationId, bulkCreateData);
121+
const result = await this.peopleService.bulkCreate(
122+
organizationId,
123+
bulkCreateData,
124+
);
120125

121126
return {
122127
...result,
123128
authType: authContext.authType,
124-
...(authContext.userId && authContext.userEmail && {
125-
authenticatedUser: {
126-
id: authContext.userId,
127-
email: authContext.userEmail,
128-
},
129-
}),
129+
...(authContext.userId &&
130+
authContext.userEmail && {
131+
authenticatedUser: {
132+
id: authContext.userId,
133+
email: authContext.userEmail,
134+
},
135+
}),
130136
};
131137
}
132138

@@ -147,12 +153,13 @@ export class PeopleController {
147153
return {
148154
...person,
149155
authType: authContext.authType,
150-
...(authContext.userId && authContext.userEmail && {
151-
authenticatedUser: {
152-
id: authContext.userId,
153-
email: authContext.userEmail,
154-
},
155-
}),
156+
...(authContext.userId &&
157+
authContext.userEmail && {
158+
authenticatedUser: {
159+
id: authContext.userId,
160+
email: authContext.userEmail,
161+
},
162+
}),
156163
};
157164
}
158165

@@ -180,12 +187,13 @@ export class PeopleController {
180187
return {
181188
...updatedMember,
182189
authType: authContext.authType,
183-
...(authContext.userId && authContext.userEmail && {
184-
authenticatedUser: {
185-
id: authContext.userId,
186-
email: authContext.userEmail,
187-
},
188-
}),
190+
...(authContext.userId &&
191+
authContext.userEmail && {
192+
authenticatedUser: {
193+
id: authContext.userId,
194+
email: authContext.userEmail,
195+
},
196+
}),
189197
};
190198
}
191199

@@ -201,17 +209,21 @@ export class PeopleController {
201209
@OrganizationId() organizationId: string,
202210
@AuthContext() authContext: AuthContextType,
203211
) {
204-
const result = await this.peopleService.deleteById(memberId, organizationId);
212+
const result = await this.peopleService.deleteById(
213+
memberId,
214+
organizationId,
215+
);
205216

206217
return {
207218
...result,
208219
authType: authContext.authType,
209-
...(authContext.userId && authContext.userEmail && {
210-
authenticatedUser: {
211-
id: authContext.userId,
212-
email: authContext.userEmail,
213-
},
214-
}),
220+
...(authContext.userId &&
221+
authContext.userEmail && {
222+
authenticatedUser: {
223+
id: authContext.userId,
224+
email: authContext.userEmail,
225+
},
226+
}),
215227
};
216228
}
217229
}

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

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
1-
import {
2-
Body,
3-
Controller,
4-
Delete,
5-
Get,
6-
Param,
7-
Patch,
8-
Post,
9-
UseGuards
1+
import {
2+
Body,
3+
Controller,
4+
Delete,
5+
Get,
6+
Param,
7+
Patch,
8+
Post,
9+
UseGuards,
1010
} from '@nestjs/common';
1111
import {
1212
ApiBody,
@@ -16,11 +16,9 @@ import {
1616
ApiResponse,
1717
ApiSecurity,
1818
ApiTags,
19+
ApiExtraModels,
1920
} from '@nestjs/swagger';
20-
import {
21-
AuthContext,
22-
OrganizationId,
23-
} from '../auth/auth-context.decorator';
21+
import { AuthContext, OrganizationId } from '../auth/auth-context.decorator';
2422
import { HybridAuthGuard } from '../auth/hybrid-auth.guard';
2523
import type { AuthContext as AuthContextType } from '../auth/types';
2624
import { CreatePolicyDto } from './dto/create-policy.dto';
@@ -34,8 +32,10 @@ import { DELETE_POLICY_RESPONSES } from './schemas/delete-policy.responses';
3432
import { POLICY_OPERATIONS } from './schemas/policy-operations';
3533
import { POLICY_PARAMS } from './schemas/policy-params';
3634
import { POLICY_BODIES } from './schemas/policy-bodies';
35+
import { PolicyResponseDto } from './dto/policy-responses.dto';
3736

3837
@ApiTags('Policies')
38+
@ApiExtraModels(PolicyResponseDto)
3939
@Controller({ path: 'policies', version: '1' })
4040
@UseGuards(HybridAuthGuard)
4141
@ApiSecurity('apikey')
@@ -106,7 +106,10 @@ export class PoliciesController {
106106
@OrganizationId() organizationId: string,
107107
@AuthContext() authContext: AuthContextType,
108108
) {
109-
const policy = await this.policiesService.create(organizationId, createData);
109+
const policy = await this.policiesService.create(
110+
organizationId,
111+
createData,
112+
);
110113

111114
return {
112115
...policy,

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import {
1919
ApiNoContentResponse,
2020
ApiSecurity,
2121
ApiTags,
22+
ApiExtraModels,
2223
} from '@nestjs/swagger';
2324
import { AttachmentsService } from '../attachments/attachments.service';
2425
import { UploadAttachmentDto } from '../attachments/upload-attachment.dto';
@@ -32,6 +33,7 @@ import {
3233
import { TasksService } from './tasks.service';
3334

3435
@ApiTags('Tasks')
36+
@ApiExtraModels(TaskResponseDto, AttachmentResponseDto)
3537
@Controller({ path: 'tasks', version: '1' })
3638
@UseGuards(HybridAuthGuard)
3739
@ApiSecurity('apikey')

0 commit comments

Comments
 (0)