-
-
Notifications
You must be signed in to change notification settings - Fork 658
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
fix: fix broken OpenAPI spec #1846
Merged
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The latest updates on your projects. Learn more about Vercel for Git ↗︎ 1 Ignored Deployment
|
Coverage report
Show new covered files 🐣
Show files with reduced coverage 🔻
Test suite run success1066 tests passing in 180 suites. Report generated by 🧪jest coverage report action from 98d8784 |
This reverts commit 8425675. Because we accept bools, strings, and numbers, this is the only way to do it.
When it ends in `schema`, the tests expect it to be included in the openapi index file.
chriswk
approved these changes
Jul 28, 2022
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.
LGTM. Also reasonable to keep 3.0 compatibility (examples/example). 👍
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR fixes a few OpenAPI spec issues that we had. It also introduces an extra validation step of the API description that we generate to help us stay more in line with the spec going forward.
Background and fixes
Using the online Swagger editor, I realized we had a number of minor issues that should be resolved. They were (primarily):
Using
examples
instead ofexample
examples
is apparently a newer addition to the spec (3.1.0
; we're on3.0.3
), and isn't recognized by a number of parsers (or generators). While this is easy to change,ajv
, which we use for validating our data, didn't recognizeexample
.To rectify this, I have added
example
as a valid keyword. It seems thatajv
might be validation against version 3.1.0 of the spec, but I'm not sure. You'd think it'd be easy to change, but I haven't found any docs for it.Empty
required
listsAccording to Smartbear's documentation:
But there was nothing validating this for our schemas and we had a few empty lists. I found an openapi validator that catches this and created tests for it. That should stop it from happening going forward.
Missing query parameters
The way we document query parameters (in the state (export) endpoint at least), did not conform to the spec, and no query parameters showed up in the swagger editor. Query parameters do not use typical object schemas. Instead, they must be a list of 'ParameterObject's. I created a
query-parameters
module to handle this.Generating types from a query param list that you can use for express's query param object, isn't easy, but a bit of TS black magic fixes that up just fine.