Support `--ruleset spectral:oas` from the command line & documentation

[FichteFoll]

While migrating to version 6, I had a major head-ache over the fact that I couldn't just add --ruleset spectral:oas to my calls because spectral interprets that as a file name instead of a "special identifer" as it does when extending. This special name is referenced all over the documentation (e.g. https://meta.stoplight.io/docs/spectral/ZG9jOjYyMDc0NQ-open-api-support), yet it took me a considerable amount of time to figure out I had to run echo "extends: spectral:oas" > .spectral.yaml to make it work.

Additionally, the auto-detection mentioned in the same page does not work either (or it wasn't removed, as I gathered from #1796 and https://github.com/stoplightio/spectral/pull/1797#discussion_r699449636).

Finally, the documentation at https://meta.stoplight.io/docs/spectral/ZG9jOjI1MTg1-spectral-cli is dishonest, as it states me it would "just work" when I run spectral lint petstore.yaml. The fact that a ruleset is required is only mentioned a whole page below.

A mention of the required changes on https://meta.stoplight.io/docs/spectral/ZG9jOjg2MDIwMDM-spectral-v5-to-v6-migration-guide would also be appreciated. Coming from no configuration, I'd expect to see instructions that get me up and running the way it was before if I just followed them.

[P0lip]

Yup, it's not possible to supply spectral:oas, and I'm not sure whether we'll ever support it. We may possibly support spectral lint --ruleset https://cdn.skypack.dev/@stoplight/spectral-rulesets, but right now it's likely to be broken due to a bug in Ajv. 😞

---

Additionally, the auto-detection mentioned in the same page does not work either (or it wasn't removed, as I gathered from #1796 and #1797 (comment)).

The auto-detection has not been removed. We just no longer apply any ruleset by default. If you meant that, then yeah, it's indeed gone.

A mention of the required changes on https://meta.stoplight.io/docs/spectral/ZG9jOjg2MDIwMDM-spectral-v5-to-v6-migration-guide would also be appreciated. Coming from no configuration, I'd expect to see instructions that get me up and running the way it was before if I just followed them.

The second point in that document explains it

however now when I look at it, I agree it might be not obvious at first glance.

We also have it in the readme

If you have some spare time, feel free to send a PR updating the documentation with the bits that you think would help you. This would be very appreciated. My apologies for any inconvenience caused!

[kscheirer]

I was thrown by this change as well. I agree with @FichteFoll, I don't like it :)

Spectral v5 this works: spectral lint petstore.yaml Spectral v6 this does not work.

My doc contains "openapi": "3.0.3", it was convenient that spectral would apply oas rules. This is similar to other linters like openapi-cli and speccy.

I understand all that's needed is a .spectral.json file. However supporting dozens of API projects - this creates a new obstacle to getting an API developer up and running. I don't see what benefit this change is giving.

[FichteFoll]

The auto-detection has not been removed. We just no longer apply any ruleset by default.

I think you mean that auto-detection only applies to the decision between OpenAPI and AsyncAPI when spectral:oas, whereas I understood it as spectral being able to tell that a document is using OpenAPI and which version automatically. I'm not sure if it has been changed since I created the issue, but the current wording is fine in that sense.

The second point in that document explains it

The problem isn't that it doesn't mention the change. It mentions that quite visibly, as does the CLI itself with its error message. What I'd have liked to see there was a simple instruction to get me going to how it worked before, since that was the default behavior of spectral for quite some time, I gather.