Repository navigation
Conversation
Here is an example of how the new markdown output will look like:Demo Bookstore APIVersion: 1.0.0 Quick view
The API impact score, also known as the "Automated Quality Screening" score, is calculated Breakdown by category
The "overall" impact score is the average (mean) of the categorized scores. The categorized scores are Scoring informationInformation about how the scoring gets calculated
Error summary
Warning summary
Detailed resultsErrorsibm-integer-attributesInteger schemas should define property 'minimum'
ibm-required-enum-properties-in-responseIn a response body, an enumeration field MUST be required
ibm-enum-casing-conventionEnum values must be snake case
ibm-required-array-properties-in-responseIn a response body, an array field MUST NOT be optional
Warningsibm-prefer-token-paginationToken-based pagination is recommended over offset/limit pagination
operation-descriptionOperation "description" must be present and non-empty string.
ibm-operationid-casing-conventionOperation ids must be snake case
ibm-operationid-naming-conventionoperationIds should follow naming convention
ibm-pagination-styleThe 'limit' parameter must be of type integer and optional with default and maximum values
ibm-success-response-exampleResponse bodies should include an example response
ibm-response-status-codesOperation responses should use status code 400 instead of 422 for invalid request payloads
ibm-string-attributesString schemas should define property 'pattern'
ibm-patch-request-content-typePATCH operations should support content types application/json-patch+json or application/merge-patch+json
ibm-parameter-descriptionParameters should have a non-empty description
ibm-schema-naming-conventionPrototype schema (POST request body) for path '/books' should use the name
ibm-array-attributesArray schemas should define a numeric 'minItems' field
ibm-error-response-schemasError container model should contain property 'trace' of type string
ibm-avoid-inline-schemasNested objects should be defined as a $ref to a named schema
|
Andris28
changed the title
pyrooka
left a comment
pyrooka
left a comment
There was a problem hiding this comment.
The output looks good so far, but we should tweak the logic a bit.
|
|
||
| // 2-col table | ||
| expect(lines[10]).toBe( | ||
| '### [ibm-integer-attributes](https://github.com/IBM/openapi-validator/blob/main/docs/ibm-cloud-rules.md#ibm-integer-attributes)' |
There was a problem hiding this comment.
According to the GH Pages deploy actions, the correct URL is https://ibm.github.io/openapi-validator/docs/ibm-cloud-rules.html. See here
| function getDocumentationURL(ruleCode) { | ||
| if (ruleCode.includes('ibm')) { | ||
| const baseUrl = | ||
| 'https://ibm.github.io/openapi-validator/docs/ibm-cloud-rules.html'; | ||
| return `${baseUrl}#${ruleCode}`; | ||
| } else { | ||
| const baseUrl = | ||
| 'https://meta.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules'; | ||
| return `${baseUrl}#${ruleCode}`; | ||
| } | ||
| } |
There was a problem hiding this comment.
Looks like you are hardcoding the documentation URL in this file. Have you checked the documentationUrl that is already exists by spectral? We already set it but needs to be updated:
I think we should leverage this when setting getting the URL.
Also, we might not even need to check the namespace of the rule (IBM or Spectral), because - hopefully - spectral rules have the same field set, pointing to the correct URL. According to the doc that I linked, the correct URL is put together by Spectral, so you don't need to do it manually
The rule name is appended to the link as an anchor.
This must be doubled checked though!
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
972f950 to
313dfba
Compare
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
pyrooka
left a comment
pyrooka
left a comment
There was a problem hiding this comment.
Left a few more comments to discuss. Also, I tend to forget this, but please also update the copyright years in the changed files.
| type: number | ||
| description: A number describing the demerit quality a rule has on an API | ||
| minimum: 0.01 | ||
|
|
| !groupedByRule[result.rule].violations.some( | ||
| v => v.line === result.line && v.path === pathStr | ||
| ) |
There was a problem hiding this comment.
Looks like if we got multiple details (violations) on the same line of the same object for the same rule, the second one is dropped, because the line and the path will match. If you also think this is possible, it must be fixed.
| if (!groupedByRule[result.rule]) { | ||
| groupedByRule[result.rule] = { | ||
| base, | ||
| docLink: result.docLink, | ||
| violations: [], | ||
| }; |
There was a problem hiding this comment.
Similarly to my other comment, only the first base value will be used from the given rule. I think it's possible that a rule emits more than one base messages. This should be validated, because there is a chance that I am missing something.
| message: r.message, | ||
| path: r.path, | ||
| rule: r.code, | ||
| docLink: rules[r.code]?.documentationUrl, |
There was a problem hiding this comment.
This can evaluate to undefined. I think it would be nicer to omit the docLink field when there is no documentation link provided. Or maybe printing an empty string would be even better, since it's more explicit. Let me know what you think.
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
Signed-off-by: András Felleg <afelleg@gmail.com>
This branch has not been deployed
2 participants
In this commit we implement a a change,
where the result of the validation contains
the documentation link to the rule that has
been violated. There is also a change for the
markdown report, to have the results grouped
by the rules.