-
-
Notifications
You must be signed in to change notification settings - Fork 222
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
ruleset: AWS Gateway #475
Comments
The most troubling part is this very subtle line:
OpenAPI v2 Schema Objects are a subset/superset/sideset of JSON Schema Draft 4, so they're asking that people write invalid OpenAPI by using valid JSON Schema instead. You can have valid OpenAPI or valid JSON Schema but you can't have both. OpenAPI v3 Schema Objects are also a subset/superset/sideset but JSON Schema draft 5 based, which luckily is basically the same thing. The said, OpenAPI v3.0 added I'm not sure how we're gonna implement this specific rule. Stuff like this is why I'm trying so hard to get OpenAPI v3.1 up to be a JSON Schema draft 8 vocabulary, so that valid JSON Schema is valid OpenAPI, but until then we get to play this headache out over and over in 100 places. 🙇♂️ |
Hello, first, thanks for this project. I use API Gateway and now need to validate an openapi3.json/yaml file before uploading it to AWS API Gateway. Spectral currently returns an error when using the This is the minimum file to reproduce the problem: openapi3.json {
"openapi": "3.0.0",
"info": {
"description": "My API",
"version": "0",
"title": "My API",
"contact": {
"email": "[email protected]"
}
},
"paths": {
"/foobar/{proxy+}": {
"x-amazon-apigateway-any-method": {
"produces": [
"application/json",
"text/html",
"text/css",
"text/javascript",
"image/*",
"font/*",
"application/font-woff2",
"application/font-woff",
"application/xhtml+xml"
],
"parameters": [
{
"name": "proxy",
"in": "path",
"type": "string",
"schema": {
"type": "string"
},
"required": false
}
]
}
}
}
} luzfcb@fabio:~/projects/foobar-apigateway$ spectral lint openapi3.json
OpenAPI 3.x detected
/Users/luzfcb/projects/foobar-apigateway/openapi3.json
1:1 warning api-servers OpenAPI `servers` must be present and non-empty array.
26:11 error path-params Path parameter "**proxy**" must have a `required` that is set to `true`.
To fix, mark this parameter as required.
26:11 error path-params Parameter "**proxy**" is not used in the path "**/passthrough/{proxy+}**".
Unused parameters are not allowed.
To fix, remove this parameter.
✖ 3 problems (2 errors, 1 warning, 0 infos) Question:With the current implementation (v4.2.0), it's possible to create or override a rule to spectral not raise an error? If yes, can you provide me an example of how the rule will look like? ps: As I did not find a Spectral plugin for pre-commit, I just created it for my use. https://github.com/luzfcb/mirrors-stoplight-spectral |
Hello @luzfcb, it's very nice to see you here!
Yes, it's possible to disable a rule or change its severity. The preferred way is creating a custom ruleset and disabling a rule. In your case, the ruleset could look as follows {
"extends": "spectral:oas",
"rules": {
"path-params": "off"
}
} If you place the ruleset in the current working directory and name it The other less recommended way is utilizing the Let me know if it did the trick.
Sweet! |
@P0lip Thanks for the quick response. After some investigation, I think I am getting an error because of this regex: https://github.com/stoplightio/spectral/blob/v4.2.0/src/rulesets/oas/functions/oasPathParam.ts#L3 In a new OAS API Gateway flavor, maybe the regex can be replaced by something like: (\{[a-zA-Z0-9_-]+\}|(\{([a-zA-Z0-9_-]*)proxy\+\}$))+ Okay, this regex is not perfect: https://regex101.com/r/4pUDTz/2/ Question: It's possible to use |
@luzfcb |
I've been bothering @philsturgeon about this on twitter :p - but just found this bug so figured I'd put it here too: |
@andylockran thank you! Did you see #1615? It might solve some of the problems you've had writing more advanced rulesets. |
This will be coming out soon but not as part of spectral itself. Keep an eye on https://github.com/stoplightio/spectral-rulesets. |
AWS Gateway says it supports OpenAPI, but it's only a subset, with some extra validation rules and other non-standard stuff. We should extend the core rulesets to support AWS-flavoured OpenAPI, to help our users navigate this tricky situation.
The following rules are taken from AWS Gateway Known Issues.
Path segments can only contain alphanumeric characters, hyphens, periods, commas, and curly braces. Path parameters must be separate path segments. For example, "resource/{path_parameter_name}" is valid; "resource{path_parameter_name}" is not.
Model names can only contain alphanumeric characters.
For input parameters, only the following attributes are supported: name, in, required, type, description. Other attributes are ignored.
The
securitySchemes
type, if used, must beapiKey
. However, OAuth 2 and HTTP Basic authentication are supported via Lambda authorizers; the OpenAPI configuration is achieved via vendor extensions.The
deprecated
field is is not supported and is dropped in exported APIs.API Gateway models are defined using JSON schema draft 4, instead of the JSON schema used by OpenAPI.
The
additionalProperties
andanyOf
keywords are not supported in Models.The
discriminator
keyword is not supported in any schema object.The
example
keyword is not supported.exclusiveMinimum
is not supported by API Gateway.The
maxItems
andminItems
tags are not included in simple request validation. To work around this, update the model after import before doing validation.oneOf
is not supported by API Gateway.The
readOnly
field is not supported.Response definitions of the
"500": {"$ref": "#/responses/UnexpectedError"}
form is not supported in the OpenAPI document root. To work around this, replace the reference by the inline schema.Numbers of the
Int32
orInt64
type are not supported. An example is shown as follows:Decimal number format type (
"format": "decimal"
) is not supported in a schema definition.In method responses, schema definition must be of an object type and cannot be of primitive types. For example,
"schema": {"type": "string"}
is not supported. However, you can work around this using the following object type:Our friends over at SwaggerHub have noticed other problems not on this list.
OAS2
OAS3
Cookie parameters (in: cookie) are not supported and are ignored.
Response code ranges (4XX) are not supported. Use specific response codes instead.
TRACE operation definitions are not supported.
The text was updated successfully, but these errors were encountered: