Skip to content

Commit 52698c6

Browse files
yelizhenden-mdbyelizhenden-mdb
committed
address the comments
1 parent 6266a94 commit 52698c6

File tree

4 files changed

+77
-34
lines changed

4 files changed

+77
-34
lines changed

‎tools/spectral/ipa/__tests__/IPA110CollectionsUsePaginatedSchema.test.js‎

Lines changed: 54 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ const componentSchemas = {
3333
},
3434
},
3535
},
36-
NonPaginatedList: {
36+
PaginatedList: {
3737
type: 'object',
3838
properties: {
3939
count: {
@@ -92,7 +92,7 @@ testRule('xgen-IPA-110-collections-use-paginated-schema', [
9292
errors: [],
9393
},
9494
{
95-
name: 'valid schemas without Paginated prefix but with correct structure',
95+
name: 'invalid schemas without Paginated prefix but with correct structure',
9696
document: {
9797
paths: {
9898
'/resources': {
@@ -118,7 +118,15 @@ testRule('xgen-IPA-110-collections-use-paginated-schema', [
118118
schemas: componentSchemas,
119119
},
120120
},
121-
errors: [],
121+
errors: [
122+
{
123+
code: 'xgen-IPA-110-collections-use-paginated-schema',
124+
message:
125+
'List methods response must reference a paginated response schema. The response should reference a schema with "Paginated" prefix',
126+
path: ['paths', '/resources', 'get', 'responses', '200', 'content', 'application/json'],
127+
severity: DiagnosticSeverity.Warning,
128+
},
129+
],
122130
},
123131
{
124132
name: 'invalid list methods without correct structure',
@@ -129,11 +137,15 @@ testRule('xgen-IPA-110-collections-use-paginated-schema', [
129137
responses: {
130138
200: {
131139
content: {
132-
'application/json': {
140+
'application/vnd.atlas.2024-08-05+json': {
133141
schema: {
134-
$ref: '#/components/schemas/NonPaginatedList',
142+
$ref: '#/components/schemas/PaginatedList',
135143
},
136144
},
145+
'application/vnd.atlas.2024-01-01+json': {
146+
schema: {},
147+
},
148+
'application/vnd.atlas.2024-03-03+json': {},
137149
},
138150
},
139151
},
@@ -151,8 +163,22 @@ testRule('xgen-IPA-110-collections-use-paginated-schema', [
151163
{
152164
code: 'xgen-IPA-110-collections-use-paginated-schema',
153165
message:
154-
'List methods must use a paginated response schema. The response should reference a schema with either a name starting with "Paginated" or contain both "totalCount" (integer) and "results" (array) fields.',
155-
path: ['paths', '/resources', 'get', 'responses', '200', 'content', 'application/json'],
166+
'List methods response must reference a paginated response schema. The response should reference a schema that contains both "totalCount" (integer) and "results" (array) fields.',
167+
path: ['paths', '/resources', 'get', 'responses', '200', 'content', 'application/vnd.atlas.2024-08-05+json'],
168+
severity: DiagnosticSeverity.Warning,
169+
},
170+
{
171+
code: 'xgen-IPA-110-collections-use-paginated-schema',
172+
message:
173+
'List methods response must reference a paginated response schema. The schema is defined inline and must reference a predefined paginated schema.',
174+
path: ['paths', '/resources', 'get', 'responses', '200', 'content', 'application/vnd.atlas.2024-01-01+json'],
175+
severity: DiagnosticSeverity.Warning,
176+
},
177+
{
178+
code: 'xgen-IPA-110-collections-use-paginated-schema',
179+
message:
180+
'List methods response must reference a paginated response schema. The List method response does not have a schema defined.',
181+
path: ['paths', '/resources', 'get', 'responses', '200', 'content', 'application/vnd.atlas.2024-03-03+json'],
156182
severity: DiagnosticSeverity.Warning,
157183
},
158184
],
@@ -168,7 +194,7 @@ testRule('xgen-IPA-110-collections-use-paginated-schema', [
168194
content: {
169195
'application/json': {
170196
schema: {
171-
$ref: '#/components/schemas/MissingTotalCount',
197+
$ref: '#/components/schemas/PaginatedMissingTotalCount',
172198
},
173199
},
174200
},
@@ -183,7 +209,7 @@ testRule('xgen-IPA-110-collections-use-paginated-schema', [
183209
components: {
184210
schemas: {
185211
...componentSchemas,
186-
MissingTotalCount: {
212+
PaginatedMissingTotalCount: {
187213
type: 'object',
188214
properties: {
189215
results: {
@@ -201,7 +227,7 @@ testRule('xgen-IPA-110-collections-use-paginated-schema', [
201227
{
202228
code: 'xgen-IPA-110-collections-use-paginated-schema',
203229
message:
204-
'List methods must use a paginated response schema. The response should reference a schema with either a name starting with "Paginated" or contain both "totalCount" (integer) and "results" (array) fields.',
230+
'List methods response must reference a paginated response schema. The response should reference a schema that contains both "totalCount" (integer) and "results" (array) fields.',
205231
path: ['paths', '/resources', 'get', 'responses', '200', 'content', 'application/json'],
206232
severity: DiagnosticSeverity.Warning,
207233
},
@@ -218,7 +244,7 @@ testRule('xgen-IPA-110-collections-use-paginated-schema', [
218244
content: {
219245
'application/json': {
220246
schema: {
221-
$ref: '#/components/schemas/MissingResults',
247+
$ref: '#/components/schemas/PaginatedMissingResults',
222248
},
223249
},
224250
},
@@ -232,7 +258,7 @@ testRule('xgen-IPA-110-collections-use-paginated-schema', [
232258
},
233259
components: {
234260
schemas: {
235-
MissingResults: {
261+
PaginatedMissingResults: {
236262
type: 'object',
237263
properties: {
238264
totalCount: {
@@ -247,7 +273,7 @@ testRule('xgen-IPA-110-collections-use-paginated-schema', [
247273
{
248274
code: 'xgen-IPA-110-collections-use-paginated-schema',
249275
message:
250-
'List methods must use a paginated response schema. The response should reference a schema with either a name starting with "Paginated" or contain both "totalCount" (integer) and "results" (array) fields.',
276+
'List methods response must reference a paginated response schema. The response should reference a schema that contains both "totalCount" (integer) and "results" (array) fields.',
251277
path: ['paths', '/resources', 'get', 'responses', '200', 'content', 'application/json'],
252278
severity: DiagnosticSeverity.Warning,
253279
},
@@ -294,28 +320,38 @@ testRule('xgen-IPA-110-collections-use-paginated-schema', [
294320
errors: [
295321
{
296322
code: 'xgen-IPA-110-collections-use-paginated-schema',
297-
message:
298-
'The schema is defined inline and must reference a predefined schema with a name starting with "Paginated".',
323+
message: 'The schema is defined inline and must reference a predefined paginated schema.',
299324
path: ['paths', '/resources', 'get', 'responses', '200', 'content', 'application/json'],
300325
severity: DiagnosticSeverity.Warning,
301326
},
302327
],
303328
},
304329
{
305-
name: 'valid schema with exception',
330+
name: 'invalid schema with exception',
306331
document: {
307332
paths: {
308333
'/resources': {
309334
get: {
310335
responses: {
311336
200: {
312337
content: {
313-
'application/json': {
338+
'application/vnd.atlas.2024-08-05+json': {
314339
'x-xgen-IPA-exception': {
315340
'xgen-IPA-110-collections-use-paginated-schema': 'Reason',
316341
},
317342
schema: {
318-
$ref: '#/components/schemas/NonPaginatedList',
343+
$ref: '#/components/schemas/PaginatedList',
344+
},
345+
},
346+
'application/vnd.atlas.2024-01-01+json': {
347+
'x-xgen-IPA-exception': {
348+
'xgen-IPA-110-collections-use-paginated-schema': 'Reason',
349+
},
350+
schema: {},
351+
},
352+
'application/vnd.atlas.2024-03-03+json': {
353+
'x-xgen-IPA-exception': {
354+
'xgen-IPA-110-collections-use-paginated-schema': 'Reason',
319355
},
320356
},
321357
},

‎tools/spectral/ipa/rulesets/IPA-110.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ rules:
1212
##### Implementation details
1313
Rule checks for the following conditions:
1414
- Only applies to List methods (GET operations that return collections of resources)
15-
- Checks that the 200 response schema references a schema with a name starting with either a name starting with "Paginated" or contain both "totalCount" (integer) and "results" (array) fields
16-
- If the referenced schema name has "Paginated" prefix, the rule assumes that the schema is paginated and does not check for "totalCount" and "results" fields
15+
- Checks if List method has a response schema defined
16+
- Checks that the 200 response schema references a schema with a "Paginated" prefix and contain both "totalCount" (integer) and "results" (array) fields
1717
message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-110-list-methods-must-use-paginated-schema'
1818
severity: warn
1919
given: '$.paths[*].get.responses.200.content'

‎tools/spectral/ipa/rulesets/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -459,8 +459,8 @@ APIs that return collections of resources must use a paginated response schema.
459459
##### Implementation details
460460
Rule checks for the following conditions:
461461
- Only applies to List methods (GET operations that return collections of resources)
462-
- Checks that the 200 response schema references a schema with a name starting with either a name starting with "Paginated" or contain both "totalCount" (integer) and "results" (array) fields
463-
- If the referenced schema name has "Paginated" prefix, the rule assumes that the schema is paginated and does not check for "totalCount" and "results" fields
462+
- Checks if List method has a response schema defined
463+
- Checks that the 200 response schema references a schema with a "Paginated" prefix and contain both "totalCount" (integer) and "results" (array) fields
464464

465465

466466

‎tools/spectral/ipa/rulesets/functions/IPA110CollectionsUsePaginatedSchema.js‎

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,7 @@ import { getSchemaNameFromRef } from './utils/methodUtils.js';
1515
import { schemaIsPaginated } from './utils/schemaUtils.js';
1616

1717
const RULE_NAME = 'xgen-IPA-110-collections-use-paginated-schema';
18-
const ERROR_MESSAGE =
19-
'List methods must use a paginated response schema. The response should reference a schema with either a name starting with "Paginated" or contain both "totalCount" (integer) and "results" (array) fields.';
18+
const ERROR_MESSAGE = 'List methods response must reference a paginated response schema.';
2019

2120
export default (input, _, { path, documentInventory }) => {
2221
const oas = documentInventory.unresolved;
@@ -31,13 +30,8 @@ export default (input, _, { path, documentInventory }) => {
3130
return;
3231
}
3332

34-
// Ignore if the List method does not have a response schema
3533
const listMethodResponse = resolveObject(oas, path);
3634

37-
if (!listMethodResponse || !listMethodResponse.schema) {
38-
return;
39-
}
40-
4135
if (hasException(listMethodResponse, RULE_NAME)) {
4236
collectException(listMethodResponse, RULE_NAME, path);
4337
return;
@@ -54,29 +48,42 @@ export default (input, _, { path, documentInventory }) => {
5448

5549
function checkViolationsAndReturnErrors(listMethodResponse, oas, path) {
5650
try {
51+
if (!listMethodResponse.schema) {
52+
return [
53+
{
54+
path,
55+
message: `${ERROR_MESSAGE} The List method response does not have a schema defined.`,
56+
},
57+
];
58+
}
59+
5760
if (!listMethodResponse.schema.$ref) {
5861
return [
5962
{
6063
path,
61-
message:
62-
'The schema is defined inline and must reference a predefined schema with a name starting with "Paginated".',
64+
message: `${ERROR_MESSAGE} The schema is defined inline and must reference a predefined paginated schema.`,
6365
},
6466
];
6567
}
6668

6769
const schemaRef = listMethodResponse.schema.$ref;
6870
const schemaName = getSchemaNameFromRef(schemaRef);
6971

70-
if (schemaName.startsWith('Paginated')) {
71-
return [];
72+
if (!schemaName.startsWith('Paginated')) {
73+
return [
74+
{
75+
path,
76+
message: `${ERROR_MESSAGE} The response should reference a schema with "Paginated" prefix.`,
77+
},
78+
];
7279
}
7380

7481
const listResponseSchema = resolveObject(oas, ['components', 'schemas', schemaName]);
7582
if (!schemaIsPaginated(listResponseSchema)) {
7683
return [
7784
{
7885
path,
79-
message: ERROR_MESSAGE,
86+
message: `${ERROR_MESSAGE} The response should reference a schema that contains both "totalCount" (integer) and "results" (array) fields.`,
8087
},
8188
];
8289
}

0 commit comments

Comments
 (0)