Remove ref links & update tests

[adilmirz]

As we're now passing Spectral's raw {{description}}; {{error}} to the end user, we should clean up the {{error}} by removing the unnecessary reference link as API Insights already handled mitigation/recommendation separately.

As a part of this, all tests also had to be updated to test/match against the new message format.

[adilmirz]

@npateriya, @coliu19

Discussion: Where new message format doesn't lead to a better user experience

Where {{description}} and {{error}} are the same

Old: Error representations include a useful human-readable message. (https://developer.cisco.com/docs/api-insights/#!api-guidelines-analyzer)
New: Error representations include a useful human-readable message.; Error representations include a useful human-readable message.
See: https://github.com/cisco-developer/api-insights-openapi-rulesets/pull/20/files#diff-8a66d52e04f9cee5af214b2398e47b2bc3f0ec50821cae7925fae86983b28718

Old: API uses path-based versioning. (https://developer.cisco.com/docs/api-insights/#!api-guidelines-analyzer)
New: API uses path-based versioning.; API uses path-based versioning.
See: https://github.com/cisco-developer/api-insights-openapi-rulesets/pull/20/files#diff-e5e461f83ba6be3fcf9a92a0b7327e4ff8651444b87d7e373b05dba5ed1f64d5

Old: API shows only major version numbers on the path; not the revision numbers. (https://developer.cisco.com/docs/api-insights/#!api-guidelines-analyzer)
New: API shows only major version numbers on the path; not the revision numbers.; API shows only major version numbers on the path; not the revision numbers.
See: https://github.com/cisco-developer/api-insights-openapi-rulesets/pull/20/files#diff-a153529541ef29325cde67eabefbb844427003211bb99f39db09ac9ad9ca9895

Where {{description}} and {{error}} have redundancy

Old: When returning a paginated collection, include a "max" query parameter (https://developer.cisco.com/docs/api-insights/#!api-guidelines-analyzer)
New: Pagination is designed using a \'max\' query parameter and \'Link\' headers per RFC 5988.; When returning a paginated collection, include a "max" query parameter
See: https://github.com/cisco-developer/api-insights-openapi-rulesets/pull/20/files#diff-79ef91f79c5bdfa1073afd31ced18a5b10250b772a01f85ac144c6be759c7e1b

Old: It is recommended to add a "sort" query parameter to sort this collection (https://developer.cisco.com/docs/api-insights/#!api-guidelines-analyzer)
New: Sorting collections is designed with a \'sort\' query parameter.; It is recommended to add a "sort" query parameter to sort this collection
See: https://github.com/cisco-developer/api-insights-openapi-rulesets/pull/20/files#diff-fcb0925a2ffdb9ee11a58ef26af424385814ecddb835f9cf207c280e7353d74a

Where meaningful information is actually removed

Old: Accept-Charset must have a default defined (https://developer.cisco.com/docs/api-insights/#!api-guidelines-analyzer)
New: HTTP headers follow the syntax specified in the corresponding RFCs.; "[0].default" property must be truthy
See: https://github.com/cisco-developer/api-insights-openapi-rulesets/pull/20/files#diff-2e6a6ece477f8a580febd19925d95cba23240a445d7908fca29bfe2885f674a0

Old: Default for Accept-Charset must be UTF-8 (https://developer.cisco.com/docs/api-insights/#!api-guidelines-analyzer)
New: HTTP headers follow the syntax specified in the corresponding RFCs.; "test" must match the pattern "^[Uu][Tt][Ff]-8$"
See: https://github.com/cisco-developer/api-insights-openapi-rulesets/pull/20/files#diff-d19f85b90c9967bbbaa3660bacbe76974185db358d89f6763943c0e071c0c0bd

Old: Date header should be type \'string\' and should not use the built-in OpenAPI format. Instead, \'pattern\' should be used to specify a custom format (https://developer.cisco.com/docs/api-insights/#!api-guidelines-analyzer)
New: HTTP headers follow the syntax specified in the corresponding RFCs.; "[0].pattern" property must be truthy
See: https://github.com/cisco-developer/api-insights-openapi-rulesets/pull/20/files#diff-9ecd8724949dd6e21e3a3ab1705c3ec7741c8b8b50ad4a0c171f8fced1354bc0

[coliu19]

For these cases, I think we have two ways to handle them. The first one may be better choice.

1. Modify the message in ruleset to make it more meaningful. so we can keep all place in same mesage-error format.
2. Specially handling for some case, not use message-error format.

[npateriya]

For these cases, I think we have two ways to handle them. The first one may be better choice.

1. Modify the message in ruleset to make it more meaningful. so we can keep all place in same mesage-error format.
2. Specially handling for some case, not use message-error format.

@coliu19 Can you please add meaningful comments for above cases, as you are most familiar with code.

[coliu19]

Take this for example. If the message is not good. we can change the rule's description in api-insights-rulesets.js for "oas2-request-heaer-date-correct-type". to something more meaningful. Here https://github.com/cisco-developer/api-insights-openapi-rulesets/blob/am-update-analyzer-message/api-insights-openapi-ruleset.js#L698

[adilmirz]

As per discussions with @npateriya & @coliu19, selectively updating message formats to address the concerns laid out here -- #20 (comment)

[npateriya]

LGTM