Deprecate documentation rules

[philsturgeon]

User story. As a Spectral CLI user who has never hard of Stoplight, I can validate the bare necessities of my OpenAPI documents, without getting any Stoplight-centric rules or opinions about what would make good quality OpenAPI-documentation in your tooling, so that I can focus on just making OAS that works. If I am interested in making better documentation and/or Stoplight specific displays I can use https://github.com/stoplightio/spectral-documentation.

Is this related to a problem?

These rules do not related to whether OpenAPI is valid or not, so moving them into an optional ruleset helps reduce noise for new users who don't know any different, giving them more time to focus on building their APIs.

Describe the solution you'd like

Many of the most opinionated rules were either removed in previous versions, or bumped down to recommended: false, but there are more we could remove now that spectral-documentation is complete.

• info-contact
• contact-properties
• info-description
• info-license
• license-url
• openapi-tags
• openapi-tags-alphabetical
• operation-description
• operation-operationId-valid-in-url
• operation-singular-tag
• operation-tags
• operation-success-response
• oas2-parameter-description
• oas3-parameter-description
• tag-description

[magicmatatjahu]

Hi! If you are going to make a PR for this please also remember to remove rules from AsyncAPI rulesets like:

• asyncapi-info-license
• asyncapi-info-contact
• asyncapi-info-contact-properties
• asyncapi-info-description
• asyncapi-info-license-url
• asyncapi-tags-alphabetical
• asyncapi-tags

They are also opinionated as in OpenAPI and work (validate) in this sam way. Also we should change asyncapi-operation-operationId from error to the warning severity, because operationId in AsyncAPI is not obligatory - or even remove that rule.

Let me know when you will wanna do that changes.

[philsturgeon]

I have started creating a new OpenAPI ruleset for this which can live in a new spectral-openapi repo, to allow spectral:oas to be deprecated.

Currently there are a few blockers.

1. oasSchema.test.ts requires spectral core in a way I'm not sure how to include. import { RulesetFunctionContext } from "@stoplight/spectral-core/src";
2. helper/tester.ts needs spectral/test-utils which is not on npm, only in the monorepo.

I'll see what I can copy paste hack for now, but I think this could be a good chance to tidy up the test-utils for public usage, so the various spectral-owasp, spectral-url-versioning, etc aren't all copy/pasting testing helpers.

[philsturgeon]

Making some progress!

https://github.com/philsturgeon/spectral-openapi