From cdd587e5f8db4d68bd3eb74d0d805f1e2ac664e1 Mon Sep 17 00:00:00 2001 From: Hadrien Milano Date: Thu, 7 Apr 2022 14:33:22 +0200 Subject: [PATCH] feat: support $ref (#1208) --- .../BasicAnnotationsReader.ts | 3 ++- src/NodeParser/AnnotatedNodeParser.ts | 15 +++++++---- src/Utils/removeUnreachable.ts | 12 ++++++--- test/valid-data-annotations.test.ts | 2 ++ test/valid-data/annotation-ref/main.ts | 23 +++++++++++++++++ test/valid-data/annotation-ref/schema.json | 25 +++++++++++++++++++ 6 files changed, 71 insertions(+), 9 deletions(-) create mode 100644 test/valid-data/annotation-ref/main.ts create mode 100644 test/valid-data/annotation-ref/schema.json diff --git a/src/AnnotationsReader/BasicAnnotationsReader.ts b/src/AnnotationsReader/BasicAnnotationsReader.ts index b19a015be..568a26189 100644 --- a/src/AnnotationsReader/BasicAnnotationsReader.ts +++ b/src/AnnotationsReader/BasicAnnotationsReader.ts @@ -5,7 +5,7 @@ import { Annotations } from "../Type/AnnotatedType"; import { symbolAtNode } from "../Utils/symbolAtNode"; export class BasicAnnotationsReader implements AnnotationsReader { - private static requiresDollar = new Set(["id", "comment"]); + private static requiresDollar = new Set(["id", "comment", "ref"]); private static textTags = new Set([ "title", "description", @@ -13,6 +13,7 @@ export class BasicAnnotationsReader implements AnnotationsReader { "format", "pattern", + "ref", // New since draft-07: "comment", diff --git a/src/NodeParser/AnnotatedNodeParser.ts b/src/NodeParser/AnnotatedNodeParser.ts index b6f015c6e..ae4b5534d 100644 --- a/src/NodeParser/AnnotatedNodeParser.ts +++ b/src/NodeParser/AnnotatedNodeParser.ts @@ -9,6 +9,7 @@ import { ReferenceType } from "../Type/ReferenceType"; import { removeUndefined } from "../Utils/removeUndefined"; import { DefinitionType } from "../Type/DefinitionType"; import { UnionType } from "../Type/UnionType"; +import { AnyType } from "../Type/AnyType"; export class AnnotatedNodeParser implements SubNodeParser { public constructor(protected childNodeParser: SubNodeParser, protected annotationsReader: AnnotationsReader) {} @@ -18,15 +19,21 @@ export class AnnotatedNodeParser implements SubNodeParser { } public createType(node: ts.Node, context: Context, reference?: ReferenceType): BaseType | undefined { + const annotatedNode = this.getAnnotatedNode(node); + let annotations = this.annotationsReader.getAnnotations(annotatedNode); + const nullable = this.getNullable(annotatedNode); + + // Short-circuit parsing the underlying type if an explicit ref annotation was passed. + if (annotations && "$ref" in annotations) { + return new AnnotatedType(new AnyType(), annotations, nullable); + } + const baseType = this.childNodeParser.createType(node, context, reference); if (baseType === undefined) { return undefined; } - const annotatedNode = this.getAnnotatedNode(node); - let annotations = this.annotationsReader.getAnnotations(annotatedNode); - // Don't return annotations for lib types such as Exclude. if (node.getSourceFile().fileName.match(/[/\\]typescript[/\\]lib[/\\]lib\.[^/\\]+\.d\.ts$/i)) { let specialCase = false; @@ -58,8 +65,6 @@ export class AnnotatedNodeParser implements SubNodeParser { } } - const nullable = this.getNullable(annotatedNode); - return !annotations && !nullable ? baseType : new AnnotatedType(baseType, annotations || {}, nullable); } diff --git a/src/Utils/removeUnreachable.ts b/src/Utils/removeUnreachable.ts index cc805223f..537cf38bb 100644 --- a/src/Utils/removeUnreachable.ts +++ b/src/Utils/removeUnreachable.ts @@ -2,6 +2,8 @@ import { JSONSchema7Definition } from "json-schema"; import { Definition } from "../Schema/Definition"; import { StringMap } from "./StringMap"; +const DEFINITION_OFFSET = "#/definitions/".length; + function addReachable( definition: Definition | JSONSchema7Definition, definitions: StringMap, @@ -12,9 +14,9 @@ function addReachable( } if (definition.$ref) { - const typeName = decodeURIComponent(definition.$ref.slice(14)); - if (reachable.has(typeName)) { - // we've already processed this definition + const typeName = decodeURIComponent(definition.$ref.slice(DEFINITION_OFFSET)); + if (reachable.has(typeName) || !isLocalRef(definition.$ref)) { + // we've already processed this definition, or this definition refers to an external schema return; } reachable.add(typeName); @@ -79,3 +81,7 @@ export function removeUnreachable( return out; } + +function isLocalRef(ref: string) { + return ref.charAt(0) === "#"; +} diff --git a/test/valid-data-annotations.test.ts b/test/valid-data-annotations.test.ts index 5f5243c24..182b3da16 100644 --- a/test/valid-data-annotations.test.ts +++ b/test/valid-data-annotations.test.ts @@ -39,5 +39,7 @@ describe("valid-data-annotations", () => { it("annotation-readOnly", assertValidSchema("annotation-readOnly", "MyObject", "basic")); + it("annotation-ref", assertValidSchema("annotation-ref", "MyObject", "extended")); + it("annotation-writeOnly", assertValidSchema("annotation-writeOnly", "MyObject", "basic")); }); diff --git a/test/valid-data/annotation-ref/main.ts b/test/valid-data/annotation-ref/main.ts new file mode 100644 index 000000000..740306ab8 --- /dev/null +++ b/test/valid-data/annotation-ref/main.ts @@ -0,0 +1,23 @@ + +export interface MyObject { + /** + * Nested description + * + * @title Nested title + * @ref http://json-schema.org/draft-07/schema# + */ + nested: MyNestedObject + + /** + * MyObject description + * + * @title MyObject title + * @ref http://json-schema.org/draft-07/schema# + */ + myObject: { [key: string]: string }; +} + +export interface MyNestedObject { + foo: string; + bar: number; +} diff --git a/test/valid-data/annotation-ref/schema.json b/test/valid-data/annotation-ref/schema.json new file mode 100644 index 000000000..ee0f42339 --- /dev/null +++ b/test/valid-data/annotation-ref/schema.json @@ -0,0 +1,25 @@ +{ + "$ref": "#/definitions/MyObject", + "$schema": "http://json-schema.org/draft-07/schema#", + "definitions": { + "MyObject": { + "additionalProperties": false, + "properties": { + "nested": { + "$ref": "http://json-schema.org/draft-07/schema#", + "title": "Nested title", + "description": "Nested description" + }, + "myObject": { + "$ref": "http://json-schema.org/draft-07/schema#", + "title": "MyObject title", + "description": "MyObject description" + } + }, + "required": [ + "nested", "myObject" + ], + "type": "object" + } + } +}