feat: add documentation link to validation result

[Andris28]

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.

[Andris28]

Here is an example of how the new markdown output will look like:

Demo Bookstore API

Version: 1.0.0

Quick view

Impact Score	Error Count	Warning Count
50 / 100	36	138

The API impact score, also known as the "Automated Quality Screening" score, is calculated
by the IBM OpenAPI Validator to help users understand the impact of the rule violations
reported by the validator. The scores are designed to help users evaluate risk and make
decisions about investing in the quality of their service's API.
For more information, see the AQS documentation.

Breakdown by category

Category	Impact Score
usability	63 / 100
security	35 / 100
robustness	51 / 100
evolution	49 / 100
overall	50 / 100

The "overall" impact score is the average (mean) of the categorized scores. The categorized scores are
inherently weighted by the scoring algorithm, so that security violations are 5 times as severe
as usability violations, evolution 3 times, and robustness 2 times.

Scoring information

Information about how the scoring gets calculated

Rule	Count	Func	Usability Impact	Security Impact	Robustness Impact	Evolution Impact	Rule Total
ibm-integer-attributes	24	24×2÷integer-schemas	4	20	8	12	44
ibm-required-enum-properties-in-response	1	1×1÷operations	0.11		0.22		0.33
ibm-enum-casing-convention	10	10×3÷operations	3.33				3.33
ibm-required-array-properties-in-response	1	1×1÷operations	0.11		0.22		0.33
ibm-prefer-token-pagination	2	2×1÷operations	0.22		0.44	0.67	1.33
operation-description	9	9×3÷operations	3		6		9
ibm-operationid-casing-convention	9	9×1÷operations	1				1
ibm-operationid-naming-convention	8	8×1÷operations	0.89				0.89
ibm-pagination-style	8	8×2÷operations	1.78		3.56		5.34
ibm-success-response-example	8	8×1÷operations	0.89				0.89
ibm-response-status-codes	1	1×1÷operations	0.11		0.22	0.33	0.66
ibm-string-attributes	77	77×2÷string-schemas	4.97	24.84	9.94	14.9	54.65
ibm-patch-request-content-type	1	1×2÷operations	0.22		0.44		0.66
ibm-parameter-description	2	2×2÷operations	0.44		0.89		1.33
ibm-schema-naming-convention	4	4×1÷operations	0.44				0.44
ibm-array-attributes	6	6×2÷array-schemas	4	20	8	12	44
ibm-error-response-schemas	2	2×2÷operations	0.44		0.89	1.33	2.66
ibm-avoid-inline-schemas	1	1×2÷operations	0.22			0.67	0.89

Error summary

Count	Percentage	Generalized Message
12	33%	Integer schemas should define property 'minimum'
12	33%	Integer schemas should define property 'maximum'
1	3%	In a response body, an enumeration field MUST be required
10	28%	Enum values must be snake case
1	3%	In a response body, an array field MUST NOT be optional

Warning summary

Count	Percentage	Generalized Message
2	1%	Token-based pagination is recommended over offset/limit pagination
9	7%	Operation "description" must be present and non-empty string.
9	7%	Operation ids must be snake case
8	6%	operationIds should follow naming convention
2	1%	The 'limit' parameter must be of type integer and optional with default and maximum values
8	6%	Response bodies should include an example response
1	1%	Operation responses should use status code 400 instead of 422 for invalid request payloads
25	18%	String schemas should define property 'pattern'
26	19%	String schemas should define property 'minLength'
26	19%	String schemas should define property 'maxLength'
1	1%	PATCH operations should support content types application/json-patch+json or application/merge-patch+json
2	1%	Parameters should have a non-empty description
1	1%	Prototype schema (POST request body) for path '/books' should use the name
2	1%	A paginated list operation should include a 'first' property in the response body schema
2	1%	A paginated list operation should include a 'next' property in the response body schema
1	1%	Collection schema for path '/books' should use the name
3	2%	Array schemas should define a numeric 'minItems' field
3	2%	Array schemas should define a numeric 'maxItems' field
1	1%	Prototype schema (POST request body) for path '/authors' should use the name
1	1%	A paginated list operation with a 'limit' query parameter must include a 'limit' property in the response body schema
1	1%	A paginated list operation with an 'offset' query parameter must include an 'offset' property in the response body schema
1	1%	Collection schema for path '/authors' should use the name
1	1%	Error container model should contain property 'trace' of type string
1	1%	Error container model must contain property 'errors' which must be an array of error models
1	1%	Nested objects should be defined as a $ref to a named schema

Detailed results

Errors

ibm-integer-attributes

Integer schemas should define property 'minimum'

Line	Path
33	paths./books.get.parameters.0.schema
39	paths./books.get.parameters.1.schema
177	paths./authors.get.parameters.0.schema
182	paths./authors.get.parameters.1.schema
302	components.schemas.Book.properties.stock_count
341	components.schemas.BookInput.properties.stock_count
364	components.schemas.BookList.properties.total_count
368	components.schemas.BookList.properties.limit
372	components.schemas.BookList.properties.offset
425	components.schemas.AuthorList.properties.total_count
445	components.schemas.Order.properties.quantity
473	components.schemas.OrderInput.properties.quantity

ibm-required-enum-properties-in-response

In a response body, an enumeration field MUST be required

Line	Path
289	components.schemas.Book.properties.genre

ibm-enum-casing-convention

Enum values must be snake case

Line	Path
293	components.schemas.Book.properties.genre.enum.0
294	components.schemas.Book.properties.genre.enum.1
295	components.schemas.Book.properties.genre.enum.2
296	components.schemas.Book.properties.genre.enum.3
297	components.schemas.Book.properties.genre.enum.4
332	components.schemas.BookInput.properties.genre.enum.0
333	components.schemas.BookInput.properties.genre.enum.1
334	components.schemas.BookInput.properties.genre.enum.2
335	components.schemas.BookInput.properties.genre.enum.3
336	components.schemas.BookInput.properties.genre.enum.4

ibm-required-array-properties-in-response

In a response body, an array field MUST NOT be optional

Line	Path
491	components.schemas.ErrorModel.properties.details

Warnings

ibm-prefer-token-pagination

Token-based pagination is recommended over offset/limit pagination

Line	Path
24	paths./books.get
169	paths./authors.get

operation-description

Operation "description" must be present and non-empty string.

Line	Path
24	paths./books.get
56	paths./books.post
88	paths./books/{book_id}.get
114	paths./books/{book_id}.patch
146	paths./books/{book_id}.delete
169	paths./authors.get
193	paths./authors.post
213	paths./authors/{author_id}.get
240	paths./orders.post

ibm-operationid-casing-convention

Operation ids must be snake case

Line	Path
25	paths./books.get.operationId
57	paths./books.post.operationId
89	paths./books/{book_id}.get.operationId
115	paths./books/{book_id}.patch.operationId
147	paths./books/{book_id}.delete.operationId
170	paths./authors.get.operationId
194	paths./authors.post.operationId
214	paths./authors/{author_id}.get.operationId
241	paths./orders.post.operationId

ibm-operationid-naming-convention

operationIds should follow naming convention

Line	Path	Detail
25	paths./books.get.operationId	operationId should be list_books but it's listBooks instead
57	paths./books.post.operationId	operationId should be create_book but it's createBook instead
89	paths./books/{book_id}.get.operationId	operationId should be get_book but it's getBook instead
115	paths./books/{book_id}.patch.operationId	operationId should be update_book but it's updateBook instead
147	paths./books/{book_id}.delete.operationId	operationId should be delete_book but it's deleteBook instead
170	paths./authors.get.operationId	operationId should be list_authors but it's listAuthors instead
194	paths./authors.post.operationId	operationId should be create_author but it's createAuthor instead
214	paths./authors/{author_id}.get.operationId	operationId should be get_author but it's getAuthor instead

ibm-pagination-style

The 'limit' parameter must be of type integer and optional with default and maximum values

Line	Path
30	paths./books.get.parameters.0
175	paths./authors.get.parameters.0
350	components.schemas.BookList
413	components.schemas.AuthorList

ibm-success-response-example

Response bodies should include an example response

Line	Path
46	paths./books.get.responses.200.content.application/json
71	paths./books.post.responses.201.content.application/json
104	paths./books/{book_id}.get.responses.200.content.application/json
136	paths./books/{book_id}.patch.responses.200.content.application/json
189	paths./authors.get.responses.200.content.application/json
208	paths./authors.post.responses.201.content.application/json
229	paths./authors/{author_id}.get.responses.200.content.application/json
255	paths./orders.post.responses.201.content.application/json

ibm-response-status-codes

Operation responses should use status code 400 instead of 422 for invalid request payloads

Line	Path
80	paths./books.post.responses.422

ibm-string-attributes

String schemas should define property 'pattern'

Line	Path
98	paths./books/{book_id}.get.parameters.0.schema
124	paths./books/{book_id}.patch.parameters.0.schema
156	paths./books/{book_id}.delete.parameters.0.schema
223	paths./authors/{author_id}.get.parameters.0.schema
277	components.schemas.Book.properties.book_id
280	components.schemas.Book.properties.title
283	components.schemas.Book.properties.author_id
286	components.schemas.Book.properties.isbn
319	components.schemas.BookInput.properties.title
322	components.schemas.BookInput.properties.author_id
325	components.schemas.BookInput.properties.isbn
384	components.schemas.Author.properties.author_id
387	components.schemas.Author.properties.name
390	components.schemas.Author.properties.bio
393	components.schemas.Author.properties.nationality
403	components.schemas.AuthorInput.properties.name
406	components.schemas.AuthorInput.properties.bio
409	components.schemas.AuthorInput.properties.nationality
439	components.schemas.Order.properties.order_id
442	components.schemas.Order.properties.book_id
458	components.schemas.Order.properties.created_at
470	components.schemas.OrderInput.properties.book_id
485	components.schemas.ErrorModel.properties.code
488	components.schemas.ErrorModel.properties.message
498	components.schemas.ErrorModel.properties.details.items.properties.field
501	components.schemas.ErrorModel.properties.details.items.properties.issue

ibm-patch-request-content-type

PATCH operations should support content types application/json-patch+json or application/merge-patch+json

Line	Path
129	paths./books/{book_id}.patch.requestBody.content.application/json

ibm-parameter-description

Parameters should have a non-empty description

Line	Path
175	paths./authors.get.parameters.0
180	paths./authors.get.parameters.1

ibm-schema-naming-convention

Prototype schema (POST request body) for path '/books' should use the name

Line	Path	Detail
311	components.schemas.BookInput	BookPrototype
350	components.schemas.BookList	BookCollection
397	components.schemas.AuthorInput	AuthorPrototype
413	components.schemas.AuthorList	AuthorCollection

ibm-array-attributes

Array schemas should define a numeric 'minItems' field

Line	Path
359	components.schemas.BookList.properties.books
420	components.schemas.AuthorList.properties.authors
491	components.schemas.ErrorModel.properties.details

ibm-error-response-schemas

Error container model should contain property 'trace' of type string

Line	Path
484	components.schemas.ErrorModel.properties

ibm-avoid-inline-schemas

Nested objects should be defined as a $ref to a named schema

Line	Path
494	components.schemas.ErrorModel.properties.details.items