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(oas): add ref name to analyzer #918

Merged
merged 5 commits into from
Dec 5, 2024
+40 −0
Merged

feat(oas): add ref name to analyzer #918

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
270ebd6
feat: add ref name to analyzer
mjcuva Dec 4, 2024
fce0168
fix: test snapshot
mjcuva Dec 4, 2024
6431f9d
fix: lint
mjcuva Dec 4, 2024
2523fd7
fix: add jsdoc about x-readme-ref-name
mjcuva Dec 4, 2024
efd3f2d
Update packages/oas/src/analyzer/index.ts
erunion Dec 5, 2024
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
6 changes: 5 additions & 1 deletion packages/oas/src/analyzer/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ export default async function analyzer(definition: OASDocument): Promise<OASAnal
const explorerDisabled = README_QUERIES.explorerDisabled(definition);
const staticHeaders = README_QUERIES.staticHeaders(definition);
const rawBody = README_QUERIES.rawBody(definition);

const refNames = README_QUERIES.refNames(definition);
erunion marked this conversation as resolved.
Show resolved Hide resolved
const analysis: OASAnalysis = {
general: {
mediaTypes: {
Expand Down Expand Up @@ -113,6 +113,10 @@ export default async function analyzer(definition: OASDocument): Promise<OASAnal
present: !!codeSampleLanguages.length,
locations: codeSampleLanguages,
},
'x-readme-ref-name': {
present: !!refNames.length,
locations: refNames,
},
},
};

Expand Down
8 changes: 8 additions & 0 deletions packages/oas/src/analyzer/queries/readme.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,3 +131,11 @@ export function staticHeaders(definition: OASDocument) {
})
.map(res => refizePointer(res.pointer));
}

/**
* Determine if a given API definition previously had references by checking if we added the
* `x-readme-ref-name` extension after dereferencing.
*/
export function refNames(definition: OASDocument) {
return query(["$..['x-readme-ref-name']"], definition).map(res => refizePointer(res.pointer));
}
6 changes: 6 additions & 0 deletions packages/oas/src/analyzer/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,12 @@ export interface OASAnalysis {
*/
raw_body?: OASAnalysisFeature;
'x-default': OASAnalysisFeature;

/**
* x-readme-ref-name is added by our tooling after dereferencing so our UI can display the
* reference name.
*/
'x-readme-ref-name': OASAnalysisFeature;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mind adding a JS doc for this since this isn't a public extension?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done! Let me know if you would word it differently

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that's great, thank you!

'x-readme.code-samples': OASAnalysisFeature;
'x-readme.explorer-enabled': OASAnalysisFeature;
'x-readme.headers': OASAnalysisFeature;
Expand Down
4 changes: 4 additions & 0 deletions packages/oas/test/analyzer/__snapshots__/index.test.ts.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,10 @@ exports[`analyzer > should should analyzer an OpenAPI definition 1`] = `
"locations": [],
"present": false,
},
"x-readme-ref-name": {
"locations": [],
"present": false,
},
"x-readme.code-samples": {
"locations": [],
"present": false,
Expand Down
17 changes: 17 additions & 0 deletions packages/oas/test/analyzer/queries/readme.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import type { OASDocument } from '../../../src/types.js';
import { describe, beforeAll, expect, it } from 'vitest';

import * as QUERIES from '../../../src/analyzer/queries/readme.js';
import Oas from '../../../src/index.js';

function loadSpec(r: any) {
return r.default as unknown as OASDocument;
Expand Down Expand Up @@ -189,4 +190,20 @@ describe('analyzer queries (ReadMe)', () => {
expect(QUERIES.authDefaults(petstore)).toHaveLength(0);
});
});

describe('`x-readme-ref-name` extension', () => {
it('should detect usage of `x-readme-ref-name` for defining reference names', () => {
const oas = Oas.init(petstore);
// Need to dereference it for this extension to be added
oas.dereference();
expect(QUERIES.refNames(oas.api)).toStrictEqual([
'#/components/schemas/ApiResponse/x-readme-ref-name',
'#/components/schemas/Category/x-readme-ref-name',
'#/components/schemas/Order/x-readme-ref-name',
'#/components/schemas/Pet/x-readme-ref-name',
'#/components/schemas/Tag/x-readme-ref-name',
'#/components/schemas/User/x-readme-ref-name',
]);
});
});
});
Loading