OAS 3.1 for JSON Schemas #530

Dashron · 2021-10-29T20:34:56Z

🧰 Changes

This is all the work necessary to support OAS 3.1 for JSON schemas.

pre OAS 3.1 your JSON schema could only be draft 04. 3.1 your JSON schema can be anything, as determined by the $schema value in your schema, the value of jsonSchemaDialect or the default, draft 2020-12.

These updates to the OAS library now ensure that the schemas you are working with always have the accurate $schema value, following the previously mentioned chain of priorities.

Along the way I converted the following to typescript

operation
get-parameters-as-json-schema

🧬 QA & Testing

tests

…t params

Dashron · 2021-11-22T21:14:02Z

There's some really ugly typing going on in here, but let's get the typescript conversion over before we do code cleanup. I gave code cleanup a shot and it was really problematic.

Thanks for the help at the end there @erunion

erunion · 2021-12-02T02:06:32Z

__tests__/lib/openapi-to-json-schema.test.ts

+  JSONSchema7,
+  JSONSchema7Definition,
+  JSONSchema7TypeName,
+} from '@typescript-eslint/experimental-utils/dist/json-schema';


Should this be @types/json-schema? If not, can that dependency get pulled from package.json?

erunion · 2021-12-02T02:09:05Z

__tests__/operation.test.ts

-    expect(operation.api).toStrictEqual(petstore);
+    expect(operation['api']).toStrictEqual(petstore);


Why the change to not use dot notation here?

At one point api was private, and this bypasses typescript's public/private check. It looks like it's no longer private though so it works with dot notation.

I think there's also a getApi() accessor on Operation if you want to use that instead.

erunion · 2021-12-02T02:11:00Z

src/lib/openapi-to-json-schema.ts

@@ -147,7 +164,9 @@ function searchForExampleByPointer(pointer, examples = []) {
        }

        // Prevent us from crashing if `examples` is a completely empty object.
-        const ex = schema.examples[keys.shift()];
+        const ex = schema.examples[keys.shift() as unknown as number];
+        // const ex = schema.examples[0];


Suggested change

// const ex = schema.examples[0];

erunion · 2021-12-02T02:15:19Z

src/lib/openapi-to-json-schema.ts

-    schema.enum = [...new Set(schema.enum)];
+  if (RMOAS.isSchema(schema, isPolymorphicAllOfChild) && 'enum' in schema && Array.isArray(schema.enum)) {
+    // If we ever target ES6 for typescript we can drop this array.from. https://stackoverflow.com/questions/33464504/using-spread-syntax-and-new-set-with-typescript/56870548
+    schema.enum = [...Array.from(new Set(schema.enum))];


Shouldn't need to do the spread operator here.

Suggested change

schema.enum = [...Array.from(new Set(schema.enum))];

schema.enum = Array.from(new Set(schema.enum));

weird, that all came from fixing some typing issues, looks to still be fine typewise without it.

erunion · 2021-12-02T02:40:25Z

src/operation.ts

  identifier: string;

  constructor(
-    api: RMOAS.OASDocument,
+    oas: Oas | RMOAS.OASDocument,


This seems off because the OAS constructor can't accept a copy of itself as its API definition, and we only ever pass this.api when we create a new instance of this class.

erunion · 2021-12-02T02:45:06Z

src/operation.ts

      });
    }

+    const oasTags = Object.fromEntries(oasTagMap);


Why the change to use Object.fromEntries here instead of checking .has() on the map?

I don't remember specifically, but I'm sure it's typing related. Happy to mess around with restoring the old version tomorrow morning if you'd like.

erunion · 2021-12-02T02:47:37Z

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

-        if (typeof components[componentType] === 'undefined') {
-          components[componentType] = {};
-        }
+        // Typescript is INCREDIBLY SLOW parsing this one line. I think it's because of the large variety of types that that object could represent


Suggested change

// Typescript is INCREDIBLY SLOW parsing this one line. I think it's because of the large variety of types that that object could represent

// @fixme Typescript is INCREDIBLY SLOW parsing this one line. I think it's because of the large variety of types that that object could represent

erunion · 2021-12-02T02:54:36Z

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

-          if (param.name && param2.name) {
-            return param.name === param2.name && param.in === param2.in;
-          } else if (param.$ref && param2.$ref) {
+          if ((param as RMOAS.ParameterObject).name && (param2 as RMOAS.ParameterObject).name) {


You might be able to clean this code up by typing param on line 215 with param: RMOS.ParameterObject? No TS failures here:

erunion · 2021-12-02T03:01:26Z

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

    type: 'object',
    properties: {},
  };

  Object.keys(headers).forEach(key => {
-    if (headers[key] && headers[key].schema) {
+    if (headers[key] && (headers[key] as OpenAPIV3.HeaderObject | OpenAPIV3_1.HeaderObject).schema) {


Might want to make a HeaderObject in rmoas.types that shortcuts having to repeat OpenAPIV3.HeaderObject | OpenAPIV3_1.HeaderObject.

erunion · 2021-12-02T03:05:34Z

I also made a couple changes for minor things I found, you can see all my changes here: https://github.com/readmeio/oas/compare//58d150e746f52e9a25fdfa4d27424ebce94b412d...1841ce8?expand=1

Pulled back some code docs that got deleted
Moved import type declarations to the top of the files they're in so we're consistent
Moved the ResponseExamples and RequestBodyExamples exports back to using the exports from get-*-examples.ts because they're already there. Also removed the | false declaration that got added because those arrays of examples will never have a falsy entry because we do .filter(Boolean) on it.

Dashron · 2021-12-02T21:51:03Z

Just pushed up fixes for everything. LMK what you think.

Dashron added 2 commits October 29, 2021 16:30

feat(operation): start the typescript conversion for operation and ge…

ec7158d

…t params

feat(operation): final operation type coverage

1c4966b

erunion mentioned this pull request Nov 1, 2021

feat: migrating more of the library to typescript #532

Merged

11 tasks

Dashron and others added 12 commits November 3, 2021 16:41

feat(jsonschema): more typescript conversions

173b7d7

Merge branch 'main' into feat/oas31SupportForJsonSchema

d2f51da

feat(oas-json-schema): more ts conversions, just tests left

038ba45

fix(oas-json-schema): more test fixes

87b5707

fix(oas-json-schema): more test fixes

b98dfee

fix(oas-json-schema): revert examples changes

40f8fb0

fix(oas-json-schema): revert some weird differences

0c10fc1

fix(oas-json-schema): revert some weird differences

99771a3

fix: update the isSchema check for allOf child schemas

91d3bcf

fix(openapi-json-schema): revert test changes

8490374

fix: adding the isPolymorphicAlLOfChild check to every isSchema call

0fdd02b

fix(get-param-json-schema): remove unnecessary code

02d87ab

Dashron marked this pull request as ready for review November 22, 2021 21:14

Dashron added 2 commits November 22, 2021 16:17

Merge branch 'main' into feat/oas31SupportForJsonSchema

93dea40

Merge branch 'main' into feat/oas31SupportForJsonSchema

4b84c98

Dashron requested a review from erunion November 29, 2021 17:17

erunion added the enhancement New feature or request label Dec 2, 2021

erunion added 7 commits December 1, 2021 17:52

Merge branch 'main' into feat/oas31SupportForJsonSchema

d19dd8d

chore: fixing some linting issues

58d150e

style: moving import type declarations to the top

08a116a

style: moving another import type to the top

8bc9165

fix: reverting some minor type and documentation changes

19baff5

chore: fixing some nitpicks

a21a324

fix: request and response examples will never have a falsy entry

1841ce8

erunion requested changes Dec 2, 2021

View reviewed changes

fix(json-schema): cleanup from pr comments

3a6df6f

erunion approved these changes Dec 6, 2021

View reviewed changes

erunion merged commit 91475da into main Dec 6, 2021

erunion deleted the feat/oas31SupportForJsonSchema branch December 6, 2021 17:04

erunion mentioned this pull request Dec 9, 2021

fix: backport a typescript compat fix that fixed enum array spreading #559

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OAS 3.1 for JSON Schemas #530

OAS 3.1 for JSON Schemas #530

Dashron commented Oct 29, 2021

Dashron commented Nov 22, 2021 •

edited

Loading

erunion Dec 2, 2021

erunion Dec 2, 2021

Dashron Dec 2, 2021

erunion Dec 2, 2021

erunion Dec 2, 2021

erunion Dec 2, 2021

Dashron Dec 2, 2021

erunion Dec 2, 2021

erunion Dec 2, 2021

Dashron Dec 2, 2021

erunion Dec 2, 2021

erunion Dec 2, 2021

erunion Dec 2, 2021

erunion commented Dec 2, 2021

Dashron commented Dec 2, 2021

		expect(operation.api).toStrictEqual(petstore);
		expect(operation['api']).toStrictEqual(petstore);

	schema.enum = [...Array.from(new Set(schema.enum))];
	schema.enum = Array.from(new Set(schema.enum));

	// Typescript is INCREDIBLY SLOW parsing this one line. I think it's because of the large variety of types that that object could represent
	// @fixme Typescript is INCREDIBLY SLOW parsing this one line. I think it's because of the large variety of types that that object could represent

OAS 3.1 for JSON Schemas #530

OAS 3.1 for JSON Schemas #530

Conversation

Dashron commented Oct 29, 2021

🧰 Changes

🧬 QA & Testing

Dashron commented Nov 22, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

erunion commented Dec 2, 2021

Dashron commented Dec 2, 2021

Dashron commented Nov 22, 2021 •

edited

Loading