Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(analyzer): improvements to reporting and circular $ref discovery #723

Merged
merged 6 commits into from
Dec 7, 2022
Merged

feat(analyzer): improvements to reporting and circular $ref discovery #723

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
17872ca
feat: improvements to the analyzer to always return valid $ref pointers
erunion Dec 7, 2022
e5e9c75
feat: addition of a new `getCircularReferences` method
erunion Dec 7, 2022
15e6d23
feat: improving the accuracy of the circularRef openapi query
erunion Dec 7, 2022
ea42154
docs: improvemnets
erunion Dec 7, 2022
6dab75c
Update src/index.ts
erunion Dec 7, 2022
d9f3d36
Update src/analyzer/queries/readme.ts
erunion Dec 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ Because this library has full TypeScript types and docblocks this README is not
| Method | Description |
| :--- | :--- |
| `#dereference()` | Dereference the current OpenAPI definition. Note that this will ignore circular references. |
| `#getCircularReferences()` | Retrieve an array of any circular `$ref` pointer that may exist wthin the OpenAPI definition. Note that this requires `#dereference()` to be called first. |
| `#getDefinition()` | Retrieve the OpenAPI definition that was fed into the `Oas` constructor. |
| `#getTags()` | Retrieve an array of all tags that exist within the API definition and are set on operations. |
| `#getPaths()` | Retrieve every operation that exists within the API definition. This returns an array of instances of the `Operation` class. |
Expand Down
30 changes: 15 additions & 15 deletions __tests__/analyzer/__snapshots__/index.test.ts.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ exports[`analyzer should should analyzer an OpenAPI definition 1`] = `
"openapi": {
"additionalProperties": {
"locations": [
"/paths/~1store~1inventory/get/responses/200/content/application~1json/schema/additionalProperties",
"#/paths/~1store~1inventory/get/responses/200/content/application~1json/schema/additionalProperties",
],
"present": true,
},
Expand Down Expand Up @@ -65,20 +65,20 @@ exports[`analyzer should should analyzer an OpenAPI definition 1`] = `
},
"xml": {
"locations": [
"/components/schemas/Category",
"/components/schemas/Order",
"/components/schemas/Pet",
"/components/schemas/Pet/properties/photoUrls",
"/components/schemas/Pet/properties/tags",
"/components/schemas/Tag",
"/components/schemas/User",
"/paths/~1pet~1findByStatus/get/responses/200/content/application~1xml",
"/paths/~1pet~1findByTags/get/responses/200/content/application~1xml",
"/paths/~1pet~1{petId}/get/responses/200/content/application~1xml",
"/paths/~1store~1order/post/responses/200/content/application~1xml",
"/paths/~1store~1order~1{orderId}/get/responses/200/content/application~1xml",
"/paths/~1user~1login/get/responses/200/content/application~1xml",
"/paths/~1user~1{username}/get/responses/200/content/application~1xml",
"#/components/schemas/Category",
"#/components/schemas/Order",
"#/components/schemas/Pet",
"#/components/schemas/Pet/properties/photoUrls",
"#/components/schemas/Pet/properties/tags",
"#/components/schemas/Tag",
"#/components/schemas/User",
"#/paths/~1pet~1findByStatus/get/responses/200/content/application~1xml",
"#/paths/~1pet~1findByTags/get/responses/200/content/application~1xml",
"#/paths/~1pet~1{petId}/get/responses/200/content/application~1xml",
"#/paths/~1store~1order/post/responses/200/content/application~1xml",
"#/paths/~1store~1order~1{orderId}/get/responses/200/content/application~1xml",
"#/paths/~1user~1login/get/responses/200/content/application~1xml",
"#/paths/~1user~1{username}/get/responses/200/content/application~1xml",
],
"present": true,
},
Expand Down
298 changes: 148 additions & 150 deletions __tests__/analyzer/queries/openapi.test.ts
View file
Open in desktop

Large diffs are not rendered by default.

24 changes: 12 additions & 12 deletions __tests__/analyzer/queries/readme.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@ describe('analyzer queries (ReadMe)', () => {
describe('`RAW_BODY`', () => {
it('should deterine if a definition is utilizing `RAW_BODY`', () => {
expect(QUERIES.rawBody(schemaTypes)).toStrictEqual([
'/paths/~1anything~1raw_body~1top-level-payloads/patch/requestBody/content/application~1json/schema',
'/paths/~1anything~1raw_body~1top-level-payloads/post/requestBody/content/application~1json/schema',
'#/paths/~1anything~1raw_body~1top-level-payloads/patch/requestBody/content/application~1json/schema',
'#/paths/~1anything~1raw_body~1top-level-payloads/post/requestBody/content/application~1json/schema',
]);
});

Expand Down Expand Up @@ -56,19 +56,19 @@ describe('analyzer queries (ReadMe)', () => {
},
},
} as any)
).toStrictEqual(['/paths/~1anything/get', '/x-readme/samples-enabled']);
).toStrictEqual(['#/paths/~1anything/get', '#/x-readme/samples-enabled']);
});

it("should not find where it doesn't exist", () => {
expect(QUERIES.codeSamplesDisabled(petstore)).toHaveLength(0);
});
});

describe('`x-reamde.proxy-enabled` extension', () => {
describe('`x-readme.proxy-enabled` extension', () => {
it('should detect usage of `x-proxy-enabled` for disabling our CORS proxy', () => {
expect(QUERIES.corsProxyDisabled(extensions)).toStrictEqual([
'/paths/~1x-proxy-enabled/patch',
'/paths/~1x-proxy-enabled/post',
'#/paths/~1x-proxy-enabled/patch',
'#/paths/~1x-proxy-enabled/post',
]);
});

Expand All @@ -80,8 +80,8 @@ describe('analyzer queries (ReadMe)', () => {
describe('`x-readme.code-samples` extension', () => {
it('should detect usage of `x-code-samples` for defining custom code samples', () => {
expect(QUERIES.customCodeSamples(extensions)).toStrictEqual([
'/paths/~1x-code-samples/get/x-code-samples',
'/paths/~1x-code-samples/post/x-readme/code-samples',
'#/paths/~1x-code-samples/get/x-code-samples',
'#/paths/~1x-code-samples/post/x-readme/code-samples',
]);
});

Expand Down Expand Up @@ -113,8 +113,8 @@ describe('analyzer queries (ReadMe)', () => {
describe('`x-readme.explorer-enabled` extension', () => {
it('should detect usage of `x-explorer-enabled` for disabling the API explorer "try it now" functionality', () => {
expect(QUERIES.explorerDisabled(extensions)).toStrictEqual([
'/paths/~1x-explorer-enabled/patch',
'/paths/~1x-explorer-enabled/post',
'#/paths/~1x-explorer-enabled/patch',
'#/paths/~1x-explorer-enabled/post',
]);
});

Expand Down Expand Up @@ -142,7 +142,7 @@ describe('analyzer queries (ReadMe)', () => {
},
};

expect(QUERIES.staticHeaders(definition)).toStrictEqual(['/x-headers', '/x-readme/headers']);
expect(QUERIES.staticHeaders(definition)).toStrictEqual(['#/x-headers', '#/x-readme/headers']);
});

it('should not detect empty `x-headers` arrays', () => {
Expand Down Expand Up @@ -180,7 +180,7 @@ describe('analyzer queries (ReadMe)', () => {
},
};

expect(QUERIES.authDefaults(definition)).toStrictEqual(['/components/securitySchemes/oauth']);
expect(QUERIES.authDefaults(definition)).toStrictEqual(['#/components/securitySchemes/oauth']);
});

it("should not find where it doesn't exist", () => {
Expand Down
47 changes: 35 additions & 12 deletions __tests__/index.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
import type * as RMOAS from '../src/rmoas.types';

import $RefParser from '@readme/json-schema-ref-parser';
import petstoreSpec from '@readme/oas-examples/3.0/json/petstore.json';

import Oas, { Operation, Webhook, utils } from '../src';
Expand Down Expand Up @@ -1464,42 +1463,66 @@ describe('#dereference()', () => {
}

it('should only dereference once when called multiple times', async () => {
const spy = jest.spyOn($RefParser, 'dereference');
const oas = new TestOas(petstoreSpec as RMOAS.OASDocument);
const spy = jest.fn();

await Promise.all([oas.dereference(), oas.dereference(), oas.dereference()]);
await Promise.all([oas.dereference({ cb: spy }), oas.dereference({ cb: spy }), oas.dereference({ cb: spy })]);

expect(spy).toHaveBeenCalledTimes(1);
expect(oas.getDereferencing()).toStrictEqual({ processing: false, complete: true });
expect(oas.getDereferencing()).toStrictEqual({ processing: false, complete: true, circularRefs: [] });
expect(oas.api.paths['/pet'].post.requestBody).not.toStrictEqual({
$ref: '#/components/requestBodies/Pet',
});

spy.mockRestore();
});

it('should only **ever** dereference once', async () => {
const spy = jest.spyOn($RefParser, 'dereference');
const oas = new TestOas(petstoreSpec as RMOAS.OASDocument);
const spy = jest.fn();

await oas.dereference();
expect(oas.getDereferencing()).toStrictEqual({ processing: false, complete: true });
await oas.dereference({ cb: spy });
expect(oas.getDereferencing()).toStrictEqual({ processing: false, complete: true, circularRefs: [] });
expect(oas.api.paths['/pet'].post.requestBody).not.toStrictEqual({
$ref: '#/components/requestBodies/Pet',
});

await oas.dereference();
expect(oas.getDereferencing()).toStrictEqual({ processing: false, complete: true });
await oas.dereference({ cb: spy });
expect(oas.getDereferencing()).toStrictEqual({ processing: false, complete: true, circularRefs: [] });
expect(oas.api.paths['/pet'].post.requestBody).not.toStrictEqual({
$ref: '#/components/requestBodies/Pet',
});

expect(spy).toHaveBeenCalledTimes(1);
spy.mockRestore();
});
});
});

describe('#getCircularReferences()', () => {
it('should throw an error if dereferencing has not yet happened', () => {
const oas = Oas.init({});

expect(() => {
oas.getCircularReferences();
}).toThrow('#dereference() must be called first in order for this method to obtain circular references.');
});

it('should be able to return circular refs in a circular schema', async () => {
const oas = await import('./__datasets__/circular.json').then(r => r.default).then(Oas.init);
await oas.dereference();

expect(oas.getCircularReferences()).toStrictEqual([
'#/components/schemas/offsetTransition/properties/offsetAfter',
'#/components/schemas/ProductStock/properties/test_param/items',
]);
});

it('should not return circular refs in a schema that has none', async () => {
const oas = Oas.init(petstoreSpec);
await oas.dereference();

expect(oas.getCircularReferences()).toHaveLength(0);
});
});

describe('#getPaths()', () => {
it('should all paths if paths are present', () => {
const paths = petstore.getPaths();
Expand Down
32 changes: 16 additions & 16 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@
"watch": "tsc --watch"
},
"dependencies": {
"@readme/json-schema-ref-parser": "^1.1.0",
"@readme/json-schema-ref-parser": "^1.2.0",
"@types/json-schema": "^7.0.11",
"json-schema-merge-allof": "^0.8.1",
"jsonpath-plus": "^7.2.0",
Expand All @@ -61,7 +61,7 @@
"@commitlint/config-conventional": "^17.3.0",
"@readme/eslint-config": "^10.3.1",
"@readme/oas-examples": "^5.7.1",
"@readme/openapi-parser": "^2.3.1",
"@readme/openapi-parser": "^2.4.0",
"@types/jest": "^29.2.4",
"@types/json-schema-merge-allof": "^0.6.1",
"@types/memoizee": "^0.4.6",
Expand Down
Loading