search

CiscoDevNet / api-insights-openapi-rulesets

Analyzers for OAS document linting as rulesets
Apache License 2.0
21 stars 9 forks source link

Remove ref links & update tests #20

Closed adilmirz closed 1 year ago

adilmirz commented 1 year ago

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 commented 1 year ago

@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 commented 1 year ago

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 commented 1 year ago

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.