Swagger file has validation errors

[dustinupdyke]

SUMMARY

Swagger file has parse errors

ISSUE TYPE

• Bug Report

STEPS TO REPRODUCE

Running the openapi.yaml file through Swagger validation (online, use https://editor.swagger.io/) fails with the following errors:

Semantic error at paths./api/v1/executions/{id}/re_run.post.parameters.1.schema.properties.tasks
Schemas with 'type: array', require a sibling 'items: ' field
Jump to line 1220
Semantic error at paths./api/v1/executions/{id}/re_run.post.parameters.1.schema.properties.reset
Schemas with 'type: array', require a sibling 'items: ' field
Jump to line 1223
Semantic error at paths./api/v1/packs/index/search.post.responses.200.schema.type
Schema "type" key must be a string
Jump to line 1845
Semantic error at paths./api/v1/policies.get.responses.200.schema.items
`items` must be an object
Jump to line 2296
Semantic error at paths./api/v1/rules/{rule_ref_or_id}
Equivalent paths are not allowed.
Jump to line 2717
Semantic error at paths./api/v1/webhooks/{url}
Equivalent paths are not allowed.
Jump to line 4206
Schema error at definitions['AliasExecution'].properties['actionalias'].properties['formats'].items
should NOT have additional properties
additionalProperty: oneOf
Jump to line 4638
Schema error at definitions['AliasExecution'].properties['actionalias'].properties['formats'].items
should be array
Jump to line 4638
Schema error at definitions['AliasExecution'].properties['actionalias'].properties['formats'].items
should match some schema in anyOf
Jump to line 4638
Schema error at definitions['AliasExecution'].properties['execution'].properties['$ref']
should be object
Jump to line 4687
Semantic error at definitions.PackIndex.properties.indexes.properties.status
Schemas with 'type: array', require a sibling 'items: ' field
Jump to line 5042
Semantic error at definitions.WebhookBody.type
Schema "type" key must be a string
Jump to line 5167
Semantic error at definitions.TokenRequest.properties.ttl.type
Schema "type" key must be a string
Jump to line 5232
Semantic error at definitions.TokenValidationRequest.properties.token.type
Schema "type" key must be a string
Jump to line 5255
Schema error at securityDefinitions['auth-token-cookie']
should NOT have additional properties
additionalProperty: name, in
Jump to line 5348
Schema error at securityDefinitions['auth-token-cookie'].type
should be equal to one of the allowed values
allowedValues: basic, oauth2
Jump to line 5350
Schema error at securityDefinitions['auth-token-cookie'].in
should be equal to one of the allowed values
allowedValues: header, query
Jump to line 5352

EXPECTED RESULTS

API Tools such as autorest or swagger-codegen would create a client API

ACTUAL RESULTS

All the tools that I've tried, fail with errors on parsing the swagger file.

[nmaludy]

I was curious why CI wasn't catching these errors, here's my investigation

Investigation

• Makefile contains lint-api-spec target https://github.com/StackStorm/st2/blob/master/Makefile#L189-L197
• lint-api-spec target calls st2common/bin/st2-validate-api-spec https://github.com/StackStorm/st2/blob/master/Makefile#L197
• st2common/bin/st2-validate-api-spec calls st2common.cmd.validate_api_spec.main
• st2common.cmd.validate_api_spec uses Prance to do its "validation" https://github.com/jfinkhaeuser/prance
• Looks like schema validation was disabled: https://github.com/StackStorm/st2/blob/master/st2common/st2common/cmd/validate_api_spec.py#L117-L118

[TunaYagci]

I can confirm this problem still exists on v3.1:
.

This also prevents swagger-codegen to generate client codes as well:

[INFO] --- openapi-generator-maven-plugin:4.2.3:generate (codegen) @ ---
[ERROR] failed to read resource listing
com.fasterxml.jackson.core.JsonParseException: Unrecognized token 'swagger': was expecting (JSON String, Number, Array, Object or token 'null', 'true' or 'false')

Note that there are things in the yaml thats not supported by Swagger/OAS 2. Things like "cookie" tag where you can see they are supported only in OAS 3:

I also like to mention that client code is successfully auto-generated if you remove duplicated & problematic paths from the yaml.

[TunaYagci]

I can see that whole api document, as v1 is not up-to-date. Most request/responses conflicting with the documentation.

hey @armab! should I expect any update here?

For example, here is the GET api/v1/pack response:

and the reality:

[arm4b]

Looks like https://github.com/StackStorm/st2/issues/4051 has more information about http://api.stackstorm.com/ issue.

As for the Swagger validation errors for StackStorm OpenAPI, - we'll be welcoming contribution fixes!

[TunaYagci]

hey @armab, thanks for the quick response!

I've inspected the issues you've opened. I'd like to add that I wasn't talking about the conflict between apidocs UI and openai.yaml, but rather that openapi.yaml is wrong by itself.

If you inspect the circleci link you posted you can see that it gets its openapi.yaml from st2-common. This is the yaml that's not true. Real responses are rather different as I've described deeper in my previous comment.

This is a blocker issue for me as I was about to generate client side automatically with swagger codegen. I managed to do that by fixing the validation errors; but fixing the actual models seems like quite a lot of task.

[DavidMeu]

@TunaYagci Can you please post your fixed version?