refactor: cleaning up the messy `getSchema` library and other improvements #581

erunion · 2022-01-17T00:47:50Z

🧰 Changes

🗑 ~~Deleting~~ Deprecating the getSchema library.
🆕 Added an Operation.getRequestBodyMediaTypes() accessor that returns a list of every media type that's supported in the operations request body.
🆕 Operation.getRequestBody() now supports retrieval of either the first JSON-like request body, or whatever is first available, if you don't supply a media type to retrieve.
- This completely replaces the much-maligned getSchema library.
🆕 Operation.getParameters() now supports retrieval and merging of common parameters.
- I've also added an override into the Callback class so it can contextually handle common callback parameters like it already supports for common summary and description.
🆕 Operation.hasParameters() is a new shortcut method for running a length check on Operation.getParameters().
♻️ getParametersAsJsonSchema() has been refactored to accept an Operation, or Callback, instance instead of an OperationObject object.
- It's also been updated internally to use the new hasParameters(), getParameters(), and getRequestBody() accessors.

🧬 QA & Testing

Everything here look ok?
All tests still passing?

…available

erunion · 2022-01-17T02:20:30Z

__tests__/__snapshots__/operation.test.ts.snap

@@ -5,160 +5,53 @@ Array [
  Object {
    "label": "Body Params",
    "schema": Object {
-      "$ref": "#/components/schemas/Pet",


I refactored the test that this snapshot is part of to dereference the petstore first, so these refs are no longer getting added into compiled JSON Schema.

erunion · 2022-01-17T02:21:44Z

src/lib/get-schema.ts

@@ -1,55 +0,0 @@
-import type * as RMOAS from '../rmoas.types';


👋 smell ya later

erunion · 2022-01-17T02:22:48Z

src/operation/get-parameters-as-json-schema.ts

-    const commonParams = getCommonParams();
-
-    if (commonParams.length !== 0) {
-      const commonParamsNotInParams = commonParams.filter((param: RMOAS.ParameterObject) => {


This code now lives within dedupeCommonParameters and is run as part of Operation.getParameters().

erunion · 2022-01-17T02:23:02Z

src/operation/get-parameters-as-json-schema.ts

@@ -162,15 +157,7 @@ export default function getParametersAsJsonSchema(
    };
  }

-  function getCommonParams() {
-    if (api && 'paths' in api && path in api.paths && 'parameters' in api.paths[path]) {


This code is just part of Operation.getParameters() now.

erunion · 2022-01-17T02:23:49Z

src/operation/get-parameters-as-json-schema.ts

+  const components = transformComponents();

  const typeKeys = Object.keys(types);
-  return [getRequestBody()]
-    .concat(...getParameters())
+  return [transformRequestBody()]
+    .concat(...transformParameters())


Renamed all these get* methods to be transform* so it's clearer what this is doing.

erunion · 2022-01-17T02:28:05Z

src/operation/get-parameters-as-json-schema.ts

-    } else if ('examples' in requestBody) {
-      examples.push({ examples: requestBody.examples });
+    // @todo this `examples` array be `Array<RMOAS.SchemaObject>` but that doesn't like the `examples` schema
+    const examples = [] as Array<any>;


This Array<any> is annoying but I had a lot of trouble with this block and the prevSchemas type in toJSONSchema.

For example if this is just const examples = []; TS throws this:

src/operation/get-parameters-as-json-schema.ts:142:73 - error TS2322: Type '({ example: any; } | { examples: Record<string, ReferenceObject | ExampleObject> | { [media: string]: ReferenceObject | ExampleObject; }; })[]' is not assignable to type 'PrevSchemasType'. Type '{ example: any; } | { examples: Record<string, ReferenceObject | ExampleObject> | { [media: string]: ReferenceObject | ExampleObject; }; }' is not assignable to type 'SchemaObject'. Type '{ examples: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3.ExampleObject> | { [media: string]: OpenAPIV3.ReferenceObject | OpenAPIV3.ExampleObject; }; }' is not assignable to type 'SchemaObject'. Type '{ examples: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3.ExampleObject> | { [media: string]: OpenAPIV3.ReferenceObject | OpenAPIV3.ExampleObject; }; }' is not assignable to type 'JSONSchema7 & { deprecated?: boolean; readOnly?: boolean; writeOnly?: boolean; example?: unknown; examples?: unknown[]; nullable?: boolean; xml?: unknown; externalDocs?: unknown; components?: ComponentsObject; 'x-readme-ref-name'?: string; }'. Type '{ examples: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3.ExampleObject> | { [media: string]: OpenAPIV3.ReferenceObject | OpenAPIV3.ExampleObject; }; }' is not assignable to type 'JSONSchema7'. Types of property 'examples' are incompatible. Type 'Record<string, ReferenceObject | ExampleObject> | { [media: string]: ReferenceObject | ExampleObject; }' is not assignable to type 'JSONSchema7Type'. Type 'Record<string, ReferenceObject | ExampleObject>' is not assignable to type 'JSONSchema7Type'. Type 'Record<string, ReferenceObject | ExampleObject>' is not assignable to type 'string'. 142 const cleanedSchema = toJSONSchema(requestSchema, { globalDefaults, prevSchemas: examples, refLogger }); ~~~~~~~~~~~ src/lib/openapi-to-json-schema.ts:33:3 33 prevSchemas?: PrevSchemasType; ~~~~~~~~~~~ The expected type comes from property 'prevSchemas' which is declared here on type 'toJsonSchemaOptions' Found 1 error.

If it's const examples = [] as Array<RMOAS.SchemaObject>; TS throws this:

src/operation/get-parameters-as-json-schema.ts:136:23 - error TS2322: Type 'Record<string, ReferenceObject | ExampleObject> | { [media: string]: ReferenceObject | ExampleObject; }' is not assignable to type 'unknown[] | (any[] & unknown[]) | (JSONSchema6Type[] & unknown[]) | (JSONSchema7Type & unknown[])'. Type 'Record<string, ReferenceObject | ExampleObject>' is not assignable to type 'unknown[] | (any[] & unknown[]) | (JSONSchema6Type[] & unknown[]) | (JSONSchema7Type & unknown[])'. Type 'Record<string, ReferenceObject | ExampleObject>' is not assignable to type 'string & unknown[]'. Type 'Record<string, ReferenceObject | ExampleObject>' is not assignable to type 'string'. 136 examples.push({ examples: mediaTypeObject.examples }); ~~~~~~~~ node_modules/openapi-types/dist/index.d.ts:80:9 80 examples?: OpenAPIV3.BaseSchemaObject['example'][]; ~~~~~~~~ The expected type comes from property 'examples' which is declared here on type 'SchemaObject' Found 1 error.

I get it's a problem with the ReferenceObject, as usual, I'm just not sure how to fight that battle here.

I dug into this a bit, I don't think it's a ReferenceObject issue. I think it's a legit type inconsistency, and very possibly a bug highlighted by ts.

If we go with the second option, Array<RMOAS.SchemaObject> it expects the examples to be Array<any>, because that's the spec for JSON schema.

But mediaTypeObject.exexamples isn't Array<any> it's Record<string, ReferenceObject | ExampleObject> as defined in OAS.

It seems line 136 of get-parameters-as-json-schema is mixing up JSON Schema examples and OAS examples.

Line 134 works because it's actually grabbing the value via example, but 136 needs to grab the value prop off each example.

e.g.

// @todo this `examples` array be `Array<RMOAS.SchemaObject>` but that doesn't like the `examples` schema const examples = [] as Array<RMOAS.SchemaObject>; if ('example' in mediaTypeObject) { examples.push({ example: mediaTypeObject.example }); } else if ('examples' in mediaTypeObject) { examples.push({ examples: Object.values(mediaTypeObject.examples).map((example: RMOAS.ExampleObject) => example.value), }); }

erunion · 2022-01-17T02:32:34Z

src/operation.ts

@@ -645,6 +714,16 @@ export class Callback extends Operation {

    return this.schema?.description ? this.schema.description.trim() : undefined;
  }
+
+  getParameters(): Array<RMOAS.ParameterObject> {


Like with the getSummary and getDescription overrides that the Callback class has it also needs one for parameters in order to support common parameters as callback common parameters exist in the schema above the callback (this.parentSchema), and not at the this.api.paths[method] level that they're at for standard operations.

A bit annoying but there's good test coverage in place.

Dashron

looks good, let's chat about my comment and once that's resolved 👍 . seems much cleaner.

erunion added 2 commits January 16, 2022 15:39

feat: extending the getRequestBody method to support pulling whats …

e1009b1

…available

feat: extending the getParameters() method to support common params

9d1a6a8

erunion added enhancement New feature or request refactor Issues about tackling technical debt labels Jan 17, 2022

erunion added 3 commits January 16, 2022 17:20

refactor: marking getSchema as deprecated

04f229b

fix: refactoring getParametersAsJsonSchema() to use Operation instances

df5c8c0

fix: dropping the getSchema library

f4007f6

erunion commented Jan 17, 2022

View reviewed changes

src/lib/get-schema.ts Outdated

@@ -1,55 +0,0 @@

import type * as RMOAS from '../rmoas.types';

Copy link

Member Author

erunion Jan 17, 2022

Choose a reason for hiding this comment

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

👋 smell ya later

erunion commented Jan 17, 2022

View reviewed changes

fix: adding a comment

9cd03a7

erunion marked this pull request as ready for review January 17, 2022 02:30

erunion requested review from a team, Dashron and julshotal and removed request for a team January 17, 2022 02:30

erunion commented Jan 17, 2022

View reviewed changes

Dashron requested changes Jan 24, 2022

View reviewed changes

fix: bring back getSchema but deprecating it

9740e7b

erunion merged commit f3f0e43 into main Jan 24, 2022

erunion deleted the fix/cleanup-the-getSchema-mess branch January 24, 2022 19:59

erunion mentioned this pull request Jan 24, 2022

fix: funky typing with how we extract examples during JSON Schema generation #585

Merged

erunion mentioned this pull request Oct 24, 2023

Get Path-level parameters with operation.getParametersAsJSONSchema() and operation.getParameters() #824

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: cleaning up the messy `getSchema` library and other improvements #581

refactor: cleaning up the messy `getSchema` library and other improvements #581

erunion commented Jan 17, 2022 •

edited

Loading

erunion Jan 17, 2022

erunion Jan 17, 2022

erunion Jan 17, 2022

erunion Jan 17, 2022

erunion Jan 17, 2022 •

edited

Loading

erunion Jan 17, 2022

Dashron Jan 24, 2022 •

edited

Loading

erunion Jan 17, 2022

Dashron left a comment

		@@ -1,55 +0,0 @@
		import type * as RMOAS from '../rmoas.types';

refactor: cleaning up the messy getSchema library and other improvements #581

refactor: cleaning up the messy getSchema library and other improvements #581

Conversation

erunion commented Jan 17, 2022 • edited Loading

🧰 Changes

🧬 QA & Testing

erunion Jan 17, 2022

Choose a reason for hiding this comment

erunion Jan 17, 2022

Choose a reason for hiding this comment

erunion Jan 17, 2022

Choose a reason for hiding this comment

erunion Jan 17, 2022

Choose a reason for hiding this comment

erunion Jan 17, 2022 • edited Loading

Choose a reason for hiding this comment

erunion Jan 17, 2022

Choose a reason for hiding this comment

Dashron Jan 24, 2022 • edited Loading

Choose a reason for hiding this comment

erunion Jan 17, 2022

Choose a reason for hiding this comment

Dashron left a comment

Choose a reason for hiding this comment

refactor: cleaning up the messy `getSchema` library and other improvements #581

refactor: cleaning up the messy `getSchema` library and other improvements #581

erunion commented Jan 17, 2022 •

edited

Loading

erunion Jan 17, 2022 •

edited

Loading

Dashron Jan 24, 2022 •

edited

Loading