-
-
Notifications
You must be signed in to change notification settings - Fork 202
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat(openapi): support OpenAPI version 3.1 #882
base: master
Are you sure you want to change the base?
Conversation
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 |
432dd0e
to
bb53f78
Compare
…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
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 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this looks good. one question regarding apiDocs.paths i.e. why might it be missing and what is the behavior when it is
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 :) |
264f83f
to
0587415
Compare
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 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 |
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:
where in line 268:
That is, 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 @SF97, thank you very much for working on this. |
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 |
And it is fixed :) All tests are passing That means this PR is complete AFAIK and can be reviewed and merged to fully support Open API 3.1, including reusable path items which I just fixed @cdimascio could you please review and let me know if there's anything that needs to be changed? |
Reviewed lightly and added a couple of comments. Hope it helps. |
Thank you |
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 formatmedia-range
but does not validate its content. This validation can be made in another PR--extension
flag. With the previous setup, the new tests weren't being picked up by the runnerOpenAPI 3.1 support
responses
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:
Closes #573 #755