feat(openapi): support OpenAPI version 3.1 #882

SF97 · 2024-01-01T13:03:56Z

This PR adds support for OpenAPI version 3.1. This has been tried before, as described in OpenAPI 3.1 support #573, but these attempts failed. Mainly due to a bug in AJV that makes it incompatible with OpenAPI version 3.1 - Support $dynamicAnchor and $recursiveAnchor in any schema location (not only root) ajv-validator/ajv#1745

This PR circumvents AJV issue by replacing all $dynamicAnchor keywords in OpenAPI schema with a direct reference, using $ref. This has been suggested by @Jackman3005 in #573 (comment), which originally came from @seriousme, which already made this workaround in his own OpenAPI schema validation library, https://github.com/seriousme/openapi-schema-validator. From what I understand this shouldn't be an issue. Using $dynamicAnchor would allow this lib to replace OpenAPI specification definitions, which it does not do.

Changes

openapi.schema.validator.ts now creates a different AJV instance that supports JSON schema 2020-12 when it detects version 3.1. This AJV instance accepts the format media-range but does not validate its content. This validation can be made in another PR
Adds OpenAPI specification 3.1 with $dynamicAnchor references changed to $ref
Change test scripts to use Mocha's --extension flag. With the previous setup, the new tests weren't being picked up by the runner

OpenAPI 3.1 support

There are some more changes introduced by Open API 3.1, but they're schema changes that are validated by AJV, so tests, although important, aren't as critical as the ones above. They are:

Ensure mutual TLS works correctly
Ensure extension prefixed with "x-oas-" is not allowed
Ensure "exclusiveMaximum" and "exclusiveMinimum" do not accept boolean values
Ensure server variable "enum" can not be empty
Ensure "jsonSchemaDialect" is supported
Ensure "style", "explode" and "allowReserved" for multipart/form-data are allowed as media types

Closes #573 #755

cdimascio · 2024-01-31T01:49:39Z

Thank you! can you help build the scaffolding and establish a pattern for 3.1 tests, enabling myself and the community to contribute and expand on them

SF97 · 2024-01-31T23:02:54Z

Thank you! can you help build the scaffolding and establish a pattern for 3.1 tests, enabling myself and the community to contribute and expand on them

Yes, I can do that! I've been really busy lately so I haven't got around to that yet

I think I'll have to time to pick it up this weekend

…supported

…ck up subdirectories Mocha was not picking up the tests in subdirectories with the provided glob. Adding --extension with the tests extension and setting the root test folder in tests fixed it

SF97 · 2024-02-05T00:42:59Z

Hello!

I just pushed the first test for OpenAPI 3.1, where we test for webhook support without any API routes, in which I found some bugs immediately 🤣 but at least I was able to fix it and the tests are passing 🥳

I created the folder test/openapi_3.1 for version 3.1 related tests. I've also added the interface DocumentV3_1 for a OpenAPI 3.1 compatible type, and refactored all references to the OpenAPI document to union both 3.0 and 3.1. I found this pretty ugly, maybe we should create an abstraction around it. Anyway, what I wanted was to at least do the first tests so we can all contribute to this PR :)

I also added an (incomplete) list of things to support in OpenAPI 3.1

I'll try to contribute as much as I can in the upcoming days. Anything that I can help with, just let me know

src/middlewares/parsers/schema.preprocessor.ts

cdimascio

this looks good. one question regarding apiDocs.paths i.e. why might it be missing and what is the behavior when it is

… considered valid

SF97 · 2024-02-29T23:54:59Z

Hello

Just added the list of things we need to ensure that work in OpenAPI 3.1. I based it on OpenAPI's own changelog. I'm currently adding tests to ensure that everything works with the 3.1 spec just fine. Just added some and I'm happy to receive contributions :)

…low request body

… default

…support

SF97 · 2024-04-28T19:12:47Z

Hello @cdimascio

I've added the most important tests. There are some more things to validate, but they're assured by AJV, thus I don't think they're critical to have this feature.

But I need help in one thing before shipping. I've added a test to ensure that pathItems is supported in components object, but it's failing. The YAML (test/openapi_3.1/resources/components_path_items.yaml) is fine, since it's parsed correctly in https://editor-next.swagger.io/, and it's according to the spec, but AJV is saying it's invalid, and I'm not sure why. It throws this error:

Can you give a little help here to ensure that we'll support this feature? After this test is passing we can proceed with a full review and add support for OpenAPI 3.1 🥳

Thank you

medranocalvo · 2024-05-03T12:18:20Z

Can you give a little help here to ensure that we'll support this feature? After this test is passing we can proceed with a full review and add support for OpenAPI 3.1 🥳

Had a look at this. As far as I understand the YAML is invalid, and swagger-editor is being lax about it.

Looking at the 3.1 schema https://github.com/cdimascio/express-openapi-validator/pull/882/files#diff-380b880ffe3121cfdcd466e6bc447b3607d1ddaea014b3167b3b9ee12611fd1e line 286, we see:

    "paths": {
      "$comment": "https://spec.openapis.org/oas/v3.1.0#paths-object",
      "type": "object",
      "patternProperties": {
        "^/": {
          "$ref": "#/$defs/path-item"
        }
      },
      "$ref": "#/$defs/specification-extensions",
      "unevaluatedProperties": false
    },

where in line 268:

        "pathItems": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/path-item-or-reference"
          }
        }

That is, paths' elements must be "#/$defs/path-item", while pathItems' elements might also be references. The yaml looks like this:

openapi: 3.1.0
info:
  title: Example specification
  version: "1.0"
servers:
  - url: /v1
components:
  pathItems: 
    entity:
      get: 
        [...]
paths:
  /entity:
    $ref: '#/components/pathItems/entity'

We try to use a reference from paths to components/pathItems, where they are only allowed in the other direction.

@SF97, thank you very much for working on this.

SF97 · 2024-05-13T22:26:56Z

@medranocalvo

Thank you very much! I took a look at the schema, and it looks like it was a bug at the schema level, which has been fixed in OAI/OpenAPI-Specification#3355, i.e. the YAML was fine, but the schema wasn't validating it correctly. I've updated the schema to the newest, and it no longer throws a schema error 😎.

The test is still failing, but I suspect what it is... I'm going to work on it

src/framework/openapi.schema.validator.ts

src/middlewares/openapi.request.validator.ts

src/middlewares/parsers/schema.preprocessor.ts

medranocalvo · 2024-05-17T10:13:41Z

Reviewed lightly and added a couple of comments. Hope it helps.

…t defined

cdimascio · 2024-05-23T01:41:29Z

Thank you

Jackman3005 · 2024-07-05T07:01:28Z

Hi @cdimascio @mdmower @SF97 I'm still looking forward to testing this as I think it will help with a number of issues I'm facing around nullable.

Where are things at right now? Is there a list of outstanding tasks we could make or is it ready for a alpha release?

Thanks in advance 🙏

SF97 · 2024-07-09T17:15:48Z

Hi @cdimascio @mdmower @SF97 I'm still looking forward to testing this as I think it will help with a number of issues I'm facing around nullable.

Where are things at right now? Is there a list of outstanding tasks we could make or is it ready for a alpha release?

Thanks in advance 🙏

Hello

From my end, it's ready. I've added all the test cases and fixed the bugs that I've found along the way. If we can't do an alpha release, you can always install it from this branch to test it out locally

huilingwei · 2024-08-06T06:03:06Z

@cdimascio @mdmower @SF97 Hi, is there any plan when this feature will be released?

patricktyndall · 2024-08-20T03:15:08Z

chiming in to express interest, particularly in unevaluatedProperties. Thanks all for the work

cdimascio · 2024-08-24T15:43:50Z

The content in this PR is now available on branch oas-3.1 and package [email protected]. please try it out.

# experimental OAS 3.1 in alpha (contributions welcome - see branch `oas-3.1` and pr-882)
npm install [email protected]

To contribute submit PRs against the oas-3.1 branch.

Eileen-34 · 2024-12-05T15:13:33Z

Do you know if koa openapi validator, which is provided by Express, supports 3.1 v OpenAPI Spec?

https://github.com/cdimascio/express-openapi-validator/tree/lerna-fastify/packages/koa-openapi-validator

SF97 · 2024-12-10T16:08:55Z

Hey @cdimascio

I think this is ready for a release, do you agree? We've given enough time for feedback and bug fixing

uwinkelvos · 2024-12-16T13:44:40Z

src/framework/types.ts

+    pathItems?: { [path: string]: PathItemObject | ReferenceObject }
+  }
+
+  export interface DocumentV3_1 extends Omit<DocumentV3, 'paths' | 'info' | 'components'> {


Suggested change

export interface DocumentV3_1 extends Omit<DocumentV3, 'paths' | 'info' | 'components'> {

export interface DocumentV3_1 extends Omit<DocumentV3, 'paths' | 'info' | 'components', 'openapi'> {

openapi: `3.1.${p}`;

To make this also compile type safe:
could then also be applied above in 3.0 with openapi: `3.0.${p}`;

* feat(openapi): support version 3.1 * test(openapi_3.1): ensure that an API with webhooks and no routes is supported * feat(openapi_3.1): adds open api 3.1 type * chore(test-scripts): run mocha with --extension instead of glob to pick up subdirectories Mocha was not picking up the tests in subdirectories with the provided glob. Adding --extension with the tests extension and setting the root test folder in tests fixed it * test(openapi-3.1): adds test to ensure an API with only components is considered valid * test(openapi-3.1): remove unnecessary import * test(openapi-3.1): add support for summary in info object * test(openapi-3.1): add support for identifier in license * test(openapi_3.1): ensure API with type set to null works correctly * test(open_api3.1): ensure that methods with non-explicit semantics allow request body * test(open_api3.1): ensure 500 is returned when server variable has no default * feat(openapi_3.1): ensure API supports an endpoint without response * feat(openapi_3.1): add full type support for open api 3.1 * test(openapi_3.1): adds test for path item support in components * fix(openapi_3.1_schema): update schema to fix bug * feat(openapi_3.1): support reusable path items * style(linting): fix linting issues * style(openapi): improve readability of version validation * docs(schema-validator): clearly state why media-range attribute is not defined * version 6.0.0-alpha.1 with initial OAS-3.1 support (from PR #882) * v6.0.0-alpha.2 * feat(openapi): support version 3.1 * test(openapi_3.1): ensure that an API with webhooks and no routes is supported * feat(openapi_3.1): adds open api 3.1 type * chore(test-scripts): run mocha with --extension instead of glob to pick up subdirectories Mocha was not picking up the tests in subdirectories with the provided glob. Adding --extension with the tests extension and setting the root test folder in tests fixed it * test(openapi-3.1): adds test to ensure an API with only components is considered valid * test(openapi-3.1): remove unnecessary import * test(openapi-3.1): add support for summary in info object * test(openapi-3.1): add support for identifier in license * test(openapi_3.1): ensure API with type set to null works correctly * test(open_api3.1): ensure that methods with non-explicit semantics allow request body * test(open_api3.1): ensure 500 is returned when server variable has no default * feat(openapi_3.1): ensure API supports an endpoint without response * feat(openapi_3.1): add full type support for open api 3.1 * test(openapi_3.1): adds test for path item support in components * fix(openapi_3.1_schema): update schema to fix bug * feat(openapi_3.1): support reusable path items * style(linting): fix linting issues * style(openapi): improve readability of version validation * docs(schema-validator): clearly state why media-range attribute is not defined * version 6.0.0-alpha.1 with initial OAS-3.1 support (from PR #882) * v6.0.0-alpha.2 * alpha.3 * feat(openapi): support version 3.1 * feat(openapi_3.1): adds open api 3.1 type * fix(openapi_3.1_schema): update schema to fix bug * style(linting): fix linting issues * fix: instantiate Ajv2020 for OAS 3.1 (#1009) * chore: create factories for ajvInstance and schema * test: writing some tests * chore: removing ts from editorconfig * chore: add eslint * update alpha 3.1 version * fix: examples/4-eov-operations-babel/package.json & examples/4-eov-operations-babel/package-lock.json to reduce vulnerabilities (#1021) The following vulnerabilities are fixed with an upgrade: - https://snyk.io/vuln/SNYK-JS-PATHTOREGEXP-8482416 Co-authored-by: snyk-bot <[email protected]> * fix: package.json & package-lock.json to reduce vulnerabilities (#1017) The following vulnerabilities are fixed with an upgrade: - https://snyk.io/vuln/SNYK-JS-PATHTOREGEXP-8482416 Co-authored-by: snyk-bot <[email protected]> * chore(deps): bump path-to-regexp and express in /examples/1-standard (#1016) Bumps [path-to-regexp](https://github.com/pillarjs/path-to-regexp) and [express](https://github.com/expressjs/express). These dependencies needed to be updated together. Updates `path-to-regexp` from 0.1.10 to 0.1.12 - [Release notes](https://github.com/pillarjs/path-to-regexp/releases) - [Changelog](https://github.com/pillarjs/path-to-regexp/blob/master/History.md) - [Commits](pillarjs/path-to-regexp@v0.1.10...v0.1.12) Updates `express` from 4.21.0 to 4.21.2 - [Release notes](https://github.com/expressjs/express/releases) - [Changelog](https://github.com/expressjs/express/blob/4.21.2/History.md) - [Commits](expressjs/express@4.21.0...4.21.2) --- updated-dependencies: - dependency-name: path-to-regexp dependency-type: indirect - dependency-name: express dependency-type: indirect ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * fix: upgrade express-openapi-validator from 5.3.7 to 5.3.8 (#1011) Snyk has created this PR to upgrade express-openapi-validator from 5.3.7 to 5.3.8. See this package in npm: express-openapi-validator See this project in Snyk: https://app.snyk.io/org/cdimascio/project/53639b22-8ff0-4bd5-97c3-ae30b20a20f4?utm_source=github&utm_medium=referral&page=upgrade-pr Co-authored-by: snyk-bot <[email protected]> * fix: upgrade express-openapi-validator from 5.3.6 to 5.3.7 (#1008) Snyk has created this PR to upgrade express-openapi-validator from 5.3.6 to 5.3.7. See this package in npm: express-openapi-validator See this project in Snyk: https://app.snyk.io/org/cdimascio/project/0ac9a5bd-9a7f-4c0e-bf8b-51d0bd4c4448?utm_source=github&utm_medium=referral&page=upgrade-pr Co-authored-by: snyk-bot <[email protected]> * fix: upgrade @apidevtools/json-schema-ref-parser from 11.7.0 to 11.7.2 (#1006) Snyk has created this PR to upgrade @apidevtools/json-schema-ref-parser from 11.7.0 to 11.7.2. See this package in npm: @apidevtools/json-schema-ref-parser See this project in Snyk: https://app.snyk.io/org/cdimascio/project/f63fb44e-f154-45ba-b1f0-20d49ea578ce?utm_source=github&utm_medium=referral&page=upgrade-pr Co-authored-by: snyk-bot <[email protected]> * adds standard example for oas-3.1 * v6.0.0.alpha.6 * update oas3.1 example * v5.4.0 - adds initial oas3.1 support * updates readme for oas3.1 --------- Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: Sergio Ferreira <[email protected]> Co-authored-by: carmine <[email protected]> Co-authored-by: Luis Philipe Fidelis <[email protected]> Co-authored-by: snyk-bot <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

cdimascio · 2024-12-25T14:23:59Z

merged via #1027

feat(openapi): support version 3.1

4f2ceaa

SF97 mentioned this pull request Jan 1, 2024

OpenAPI 3.1 support #573

Closed

SF97 added 2 commits February 5, 2024 00:22

test(openapi_3.1): ensure that an API with webhooks and no routes is …

1894d84

…supported

feat(openapi_3.1): adds open api 3.1 type

bb53f78

SF97 force-pushed the feat/openapi-3.1-support branch from 432dd0e to bb53f78 Compare February 5, 2024 00:32

chore(test-scripts): run mocha with --extension instead of glob to pi…

0c4f24c

…ck up subdirectories Mocha was not picking up the tests in subdirectories with the provided glob. Adding --extension with the tests extension and setting the root test folder in tests fixed it

SF97 marked this pull request as draft February 5, 2024 00:49

cdimascio reviewed Feb 9, 2024

View reviewed changes

src/middlewares/parsers/schema.preprocessor.ts Show resolved Hide resolved

cdimascio reviewed Feb 9, 2024

View reviewed changes

sdesalas mentioned this pull request Feb 14, 2024

OpenAPI v3.1 Support PayU/openapi-validator-middleware#181

Open

SF97 added 4 commits February 29, 2024 23:28

test(openapi-3.1): adds test to ensure an API with only components is…

289bd03

… considered valid

test(openapi-3.1): remove unnecessary import

0e6ae31

test(openapi-3.1): add support for summary in info object

3161312

test(openapi-3.1): add support for identifier in license

7698f02

SF97 added 2 commits March 31, 2024 12:45

test(openapi_3.1): ensure API with type set to null works correctly

15d9049

test(open_api3.1): ensure that methods with non-explicit semantics al…

0587415

…low request body

SF97 force-pushed the feat/openapi-3.1-support branch from 264f83f to 0587415 Compare March 31, 2024 22:33

SF97 added 4 commits April 1, 2024 00:14

test(open_api3.1): ensure 500 is returned when server variable has no…

415de44

… default

feat(openapi_3.1): ensure API supports an endpoint without response

7bcf518

Merge remote-tracking branch 'upstream/master' into feat/openapi-3.1-…

782a70a

…support

feat(openapi_3.1): add full type support for open api 3.1

4584261

SF97 marked this pull request as ready for review April 28, 2024 18:46

test(openapi_3.1): adds test for path item support in components

9c58166

medranocalvo reviewed May 17, 2024

View reviewed changes

src/framework/openapi.schema.validator.ts Outdated Show resolved Hide resolved

medranocalvo reviewed May 17, 2024

View reviewed changes

src/framework/openapi.schema.validator.ts Outdated Show resolved Hide resolved

medranocalvo reviewed May 17, 2024

View reviewed changes

src/middlewares/openapi.request.validator.ts Outdated Show resolved Hide resolved

medranocalvo reviewed May 17, 2024

View reviewed changes

src/middlewares/parsers/schema.preprocessor.ts Outdated Show resolved Hide resolved

SF97 added 3 commits May 20, 2024 20:51

style(linting): fix linting issues

ddc0ebc

style(openapi): improve readability of version validation

2cae4b5

docs(schema-validator): clearly state why media-range attribute is no…

81b45ee

…t defined

mdmower mentioned this pull request Jun 2, 2024

Many updates - soliciting feedback #926

Closed

Merge branch 'master' into feat/openapi-3.1-support

ffd7468

patricktyndall mentioned this pull request Aug 20, 2024

oneOf with (additionalProperties: false) and (validateResponses: removeAdditional setting) does not work as expected #740

Open

cdimascio pushed a commit that referenced this pull request Aug 24, 2024

version 6.0.0-alpha.1 with initial OAS-3.1 support (from PR #882)

ebb9b25

meenakshi2468 mentioned this pull request Aug 29, 2024

P-26 | Protocol server supporting Open API Specification 3.1 beckn/protocol-server#202

Open

14 tasks

cdimascio pushed a commit that referenced this pull request Sep 1, 2024

version 6.0.0-alpha.1 with initial OAS-3.1 support (from PR #882)

f842723

rajaneeshk90 mentioned this pull request Oct 15, 2024

Mobility Layer2 config: check out the issues with validation with openAPI version 3.1 beckn/beckn-onix#266

Closed

4 tasks

uwinkelvos reviewed Dec 16, 2024

View reviewed changes

cdimascio mentioned this pull request Dec 24, 2024

feat(openapi): support OpenAPI version 3.1 (extends PR #882) #1027

Merged

cdimascio closed this Dec 25, 2024

uwinkelvos mentioned this pull request Dec 27, 2024

re-enable keywords now properly supported #1031

Merged

SF97 deleted the feat/openapi-3.1-support branch December 29, 2024 12:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(openapi): support OpenAPI version 3.1 #882

feat(openapi): support OpenAPI version 3.1 #882

SF97 commented Jan 1, 2024 •

edited

Loading

cdimascio commented Jan 31, 2024

SF97 commented Jan 31, 2024 •

edited

Loading

SF97 commented Feb 5, 2024 •

edited

Loading

cdimascio left a comment

SF97 commented Feb 29, 2024

SF97 commented Apr 28, 2024

medranocalvo commented May 3, 2024

SF97 commented May 13, 2024

medranocalvo commented May 17, 2024

cdimascio commented May 23, 2024

Jackman3005 commented Jul 5, 2024 •

edited

Loading

SF97 commented Jul 9, 2024

huilingwei commented Aug 6, 2024

patricktyndall commented Aug 20, 2024

cdimascio commented Aug 24, 2024 •

edited

Loading

Eileen-34 commented Dec 5, 2024 •

edited

Loading

SF97 commented Dec 10, 2024 •

edited

Loading

uwinkelvos Dec 16, 2024 •

edited

Loading

cdimascio commented Dec 25, 2024

	export interface DocumentV3_1 extends Omit<DocumentV3, 'paths' \| 'info' \| 'components'> {
	export interface DocumentV3_1 extends Omit<DocumentV3, 'paths' \| 'info' \| 'components', 'openapi'> {
	openapi: `3.1.${p}`;

feat(openapi): support OpenAPI version 3.1 #882

feat(openapi): support OpenAPI version 3.1 #882

Conversation

SF97 commented Jan 1, 2024 • edited Loading

Changes

OpenAPI 3.1 support

cdimascio commented Jan 31, 2024

SF97 commented Jan 31, 2024 • edited Loading

SF97 commented Feb 5, 2024 • edited Loading

cdimascio left a comment

Choose a reason for hiding this comment

SF97 commented Feb 29, 2024

SF97 commented Apr 28, 2024

medranocalvo commented May 3, 2024

SF97 commented May 13, 2024

medranocalvo commented May 17, 2024

cdimascio commented May 23, 2024

Jackman3005 commented Jul 5, 2024 • edited Loading

SF97 commented Jul 9, 2024

huilingwei commented Aug 6, 2024

patricktyndall commented Aug 20, 2024

cdimascio commented Aug 24, 2024 • edited Loading

Eileen-34 commented Dec 5, 2024 • edited Loading

SF97 commented Dec 10, 2024 • edited Loading

uwinkelvos Dec 16, 2024 • edited Loading

Choose a reason for hiding this comment

cdimascio commented Dec 25, 2024

SF97 commented Jan 1, 2024 •

edited

Loading

SF97 commented Jan 31, 2024 •

edited

Loading

SF97 commented Feb 5, 2024 •

edited

Loading

Jackman3005 commented Jul 5, 2024 •

edited

Loading

cdimascio commented Aug 24, 2024 •

edited

Loading

Eileen-34 commented Dec 5, 2024 •

edited

Loading

SF97 commented Dec 10, 2024 •

edited

Loading

uwinkelvos Dec 16, 2024 •

edited

Loading