diff --git a/README.md b/README.md index 0d458e4..011cc3c 100644 --- a/README.md +++ b/README.md @@ -90,6 +90,17 @@ remain the same if a type argument is not given. If a type argument is given, the `options` for each will be the third argument. +### Descriptions + +If the `description` key is present in the options to `.attribute` or +`.relationship`, it will be used in the provided TypeScript Schema generator as +a comment for the property. The comment should show up in the LSP hover info. + +By default, the `description` is inferred from the ActiveRecord column comment +if it exists. Examples of both in +[spec/example/resources/exhaustive_resource](./spec/example/app/resources/exhaustive_resource.rb) +and its resulting [TypeScript schema](./spec/example/test/files/schema.ts). + ## Generators This gem provides generators for JSON Schema and TypeScript schemas via diff --git a/spec/anchor/example_schema_snapshot_spec.rb b/spec/anchor/example_schema_snapshot_spec.rb index a46902b..b58427e 100644 --- a/spec/anchor/example_schema_snapshot_spec.rb +++ b/spec/anchor/example_schema_snapshot_spec.rb @@ -9,15 +9,10 @@ def self.snapshot_test(filename, generate) unless File.file?(path) File.open(path, "w") { |file| file.write(schema) } end - expected_schema = File.read(path) - if ENV["THOR_MERGE"] && expected_schema != schema - SnapshotUpdate.prompt(path, schema) - expect(File.read(path)).to eql(schema) - return - end + SnapshotUpdate.prompt(path, schema) if ENV["THOR_MERGE"] && File.read(path) != schema - expect(expected_schema).to eql(schema) + expect(File.read(path)).to eql(schema) end end diff --git a/spec/example/app/resources/exhaustive_resource.rb b/spec/example/app/resources/exhaustive_resource.rb index 47e2286..0c6ac18 100644 --- a/spec/example/app/resources/exhaustive_resource.rb +++ b/spec/example/app/resources/exhaustive_resource.rb @@ -15,6 +15,7 @@ class AssertedObject < Types::Object attribute :asserted_maybe_object, Types::Maybe.new(AssertedObject) attribute :asserted_array_record, Types::Array.new(Types::Record.new(Types::Integer)) attribute :asserted_union, Types::Union.new([Types::String, Types::Float]) + attribute :with_description, Types::String, description: "This is a provided description." attribute :inferred_unknown attribute :uuid @@ -63,4 +64,6 @@ def asserted_union = 2 def inferred_unknown = nil def resource_overridden = "resource_overridden" + + def with_description = "with_description" end diff --git a/spec/example/test/files/all_fields_false_schema.ts b/spec/example/test/files/all_fields_false_schema.ts index c9ebd5d..0970a91 100644 --- a/spec/example/test/files/all_fields_false_schema.ts +++ b/spec/example/test/files/all_fields_false_schema.ts @@ -59,6 +59,8 @@ export type Exhaustive = { }>; assertedArrayRecord: Array>; assertedUnion: string | number; + /** This is a provided description. */ + withDescription: string; inferredUnknown: unknown; uuid: string; string: string; diff --git a/spec/example/test/files/json_schema.json b/spec/example/test/files/json_schema.json index fdf45af..e432b53 100644 --- a/spec/example/test/files/json_schema.json +++ b/spec/example/test/files/json_schema.json @@ -1 +1 @@ -{"$schema":"https://json-schema.org/draft-07/schema","title":"Schema","type":"object","properties":{"comment":{"$ref":"#/$defs/Comment"},"user":{"$ref":"#/$defs/User"},"post":{"$ref":"#/$defs/Post"},"exhaustive":{"$ref":"#/$defs/Exhaustive"}},"required":["comment","user","post","exhaustive"],"additionalProperties":false,"$defs":{"Comment":{"type":"object","properties":{"id":{"type":"number"},"type":{"enum":["comments"]},"text":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"relationships":{"type":"object","properties":{"user":{"$ref":"#/$defs/User"},"deletedBy":{"$ref":"#/$defs/User"},"commentable":{"oneOf":[{"$ref":"#/$defs/User"},{"$ref":"#/$defs/Post"}]}},"required":["user"],"additionalProperties":false}},"required":["id","type","text","createdAt","updatedAt","relationships"],"additionalProperties":false},"User":{"type":"object","properties":{"id":{"type":"number"},"type":{"enum":["users"]},"name":{"type":"string"},"role":{"enum":[{"value":"admin"},{"value":"content_creator"},{"value":"external"},{"value":"guest"},{"value":"system"}]},"relationships":{"type":"object","properties":{"comments":{"type":"array","items":{"$ref":"#/$defs/Comment"}},"posts":{"type":"array","items":{"$ref":"#/$defs/Post"}}},"required":["comments","posts"],"additionalProperties":false}},"required":["id","type","name","role","relationships"],"additionalProperties":false},"Post":{"type":"object","properties":{"id":{"type":"number"},"type":{"enum":["posts"]},"description":{"type":"string"},"relationships":{"type":"object","properties":{"user":{"$ref":"#/$defs/User"},"comments":{"type":"array","items":{"$ref":"#/$defs/Comment"}},"participants":{"type":"array","items":{"$ref":"#/$defs/User"}}},"required":["user","comments","participants"],"additionalProperties":false}},"required":["id","type","description","relationships"],"additionalProperties":false},"Exhaustive":{"type":"object","properties":{"id":{"type":"number"},"type":{"enum":["exhaustives"]},"assertedString":{"type":"string"},"assertedNumber":{"type":"number"},"assertedBoolean":{"type":"boolean"},"assertedNull":{"type":"null"},"assertedUnknown":{},"assertedObject":{"type":"object","properties":{"a":{"enum":["a"]},"b-dash":{"enum":[1]},"c":{"oneOf":[{"type":"string"},{"type":"null"}]},"d_optional":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["a","b-dash","c"],"additionalProperties":false},"assertedMaybeObject":{"oneOf":[{"type":"object","properties":{"a":{"enum":["a"]},"b-dash":{"enum":[1]},"c":{"oneOf":[{"type":"string"},{"type":"null"}]},"d_optional":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["a","b-dash","c"],"additionalProperties":false},{"type":"null"}]},"assertedArrayRecord":{"type":"array","items":{"type":"object","additionalProperties":"true"}},"assertedUnion":{"oneOf":[{"type":"string"},{"type":"number"}]},"inferredUnknown":{},"uuid":{"type":"string"},"string":{"type":"string"},"maybeString":{"type":"string"},"text":{"type":"string"},"integer":{"type":"number"},"float":{"type":"number"},"decimal":{"type":"string"},"datetime":{"type":"string"},"timestamp":{"type":"string"},"time":{"type":"string"},"date":{"type":"string"},"boolean":{"type":"boolean"},"arrayString":{"type":"array","items":{"type":"string"}},"maybeArrayString":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"json":{"type":"object","additionalProperties":"true"},"jsonb":{"type":"object","additionalProperties":"true"},"daterange":{},"enum":{},"virtualUpcasedString":{"oneOf":[{"type":"string"},{"type":"null"}]},"loljk":{"enum":["never"]},"delegatedMaybeString":{"type":"string"},"modelOverridden":{},"resourceOverridden":{},"withComment":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["id","type","assertedString","assertedNumber","assertedBoolean","assertedNull","assertedUnknown","assertedObject","assertedMaybeObject","assertedArrayRecord","assertedUnion","inferredUnknown","uuid","string","maybeString","text","integer","float","decimal","datetime","timestamp","time","date","boolean","arrayString","maybeArrayString","json","jsonb","daterange","enum","virtualUpcasedString","loljk","delegatedMaybeString","modelOverridden","resourceOverridden","withComment"],"additionalProperties":false}}} \ No newline at end of file +{"$schema":"https://json-schema.org/draft-07/schema","title":"Schema","type":"object","properties":{"comment":{"$ref":"#/$defs/Comment"},"user":{"$ref":"#/$defs/User"},"post":{"$ref":"#/$defs/Post"},"exhaustive":{"$ref":"#/$defs/Exhaustive"}},"required":["comment","user","post","exhaustive"],"additionalProperties":false,"$defs":{"Comment":{"type":"object","properties":{"id":{"type":"number"},"type":{"enum":["comments"]},"text":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"relationships":{"type":"object","properties":{"user":{"$ref":"#/$defs/User"},"deletedBy":{"$ref":"#/$defs/User"},"commentable":{"oneOf":[{"$ref":"#/$defs/User"},{"$ref":"#/$defs/Post"}]}},"required":["user"],"additionalProperties":false}},"required":["id","type","text","createdAt","updatedAt","relationships"],"additionalProperties":false},"User":{"type":"object","properties":{"id":{"type":"number"},"type":{"enum":["users"]},"name":{"type":"string"},"role":{"enum":[{"value":"admin"},{"value":"content_creator"},{"value":"external"},{"value":"guest"},{"value":"system"}]},"relationships":{"type":"object","properties":{"comments":{"type":"array","items":{"$ref":"#/$defs/Comment"}},"posts":{"type":"array","items":{"$ref":"#/$defs/Post"}}},"required":["comments","posts"],"additionalProperties":false}},"required":["id","type","name","role","relationships"],"additionalProperties":false},"Post":{"type":"object","properties":{"id":{"type":"number"},"type":{"enum":["posts"]},"description":{"type":"string"},"relationships":{"type":"object","properties":{"user":{"$ref":"#/$defs/User"},"comments":{"type":"array","items":{"$ref":"#/$defs/Comment"}},"participants":{"type":"array","items":{"$ref":"#/$defs/User"}}},"required":["user","comments","participants"],"additionalProperties":false}},"required":["id","type","description","relationships"],"additionalProperties":false},"Exhaustive":{"type":"object","properties":{"id":{"type":"number"},"type":{"enum":["exhaustives"]},"assertedString":{"type":"string"},"assertedNumber":{"type":"number"},"assertedBoolean":{"type":"boolean"},"assertedNull":{"type":"null"},"assertedUnknown":{},"assertedObject":{"type":"object","properties":{"a":{"enum":["a"]},"b-dash":{"enum":[1]},"c":{"oneOf":[{"type":"string"},{"type":"null"}]},"d_optional":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["a","b-dash","c"],"additionalProperties":false},"assertedMaybeObject":{"oneOf":[{"type":"object","properties":{"a":{"enum":["a"]},"b-dash":{"enum":[1]},"c":{"oneOf":[{"type":"string"},{"type":"null"}]},"d_optional":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["a","b-dash","c"],"additionalProperties":false},{"type":"null"}]},"assertedArrayRecord":{"type":"array","items":{"type":"object","additionalProperties":"true"}},"assertedUnion":{"oneOf":[{"type":"string"},{"type":"number"}]},"withDescription":{"type":"string"},"inferredUnknown":{},"uuid":{"type":"string"},"string":{"type":"string"},"maybeString":{"type":"string"},"text":{"type":"string"},"integer":{"type":"number"},"float":{"type":"number"},"decimal":{"type":"string"},"datetime":{"type":"string"},"timestamp":{"type":"string"},"time":{"type":"string"},"date":{"type":"string"},"boolean":{"type":"boolean"},"arrayString":{"type":"array","items":{"type":"string"}},"maybeArrayString":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"json":{"type":"object","additionalProperties":"true"},"jsonb":{"type":"object","additionalProperties":"true"},"daterange":{},"enum":{},"virtualUpcasedString":{"oneOf":[{"type":"string"},{"type":"null"}]},"loljk":{"enum":["never"]},"delegatedMaybeString":{"type":"string"},"modelOverridden":{},"resourceOverridden":{},"withComment":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["id","type","assertedString","assertedNumber","assertedBoolean","assertedNull","assertedUnknown","assertedObject","assertedMaybeObject","assertedArrayRecord","assertedUnion","withDescription","inferredUnknown","uuid","string","maybeString","text","integer","float","decimal","datetime","timestamp","time","date","boolean","arrayString","maybeArrayString","json","jsonb","daterange","enum","virtualUpcasedString","loljk","delegatedMaybeString","modelOverridden","resourceOverridden","withComment"],"additionalProperties":false}}} \ No newline at end of file diff --git a/spec/example/test/files/schema.ts b/spec/example/test/files/schema.ts index c8ac086..3a0fbe4 100644 --- a/spec/example/test/files/schema.ts +++ b/spec/example/test/files/schema.ts @@ -67,6 +67,8 @@ export type Exhaustive = { }>; assertedArrayRecord: Array>; assertedUnion: string | number; + /** This is a provided description. */ + withDescription: string; inferredUnknown: unknown; uuid: string; string: string; diff --git a/spec/example/test/files/test_schema.ts b/spec/example/test/files/test_schema.ts index c7917e2..7e1f83f 100644 --- a/spec/example/test/files/test_schema.ts +++ b/spec/example/test/files/test_schema.ts @@ -64,6 +64,8 @@ export type Exhaustive = { }>; assertedArrayRecord: Array>; assertedUnion: string | number; + /** This is a provided description. */ + withDescription: string; inferredUnknown: unknown; uuid: string; string: string;