Skip to content

refactor: adjust rule details format in generated markdown report #740

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: 2.x
Choose a base branch
from

Conversation

dpopp07
Copy link
Contributor

@dpopp07 dpopp07 commented Apr 10, 2025

This is something I'm proposing for 2.x. Happy to take feedback on the design!


Rather than generating one big table, with lots of wide columns, this generates one table per violation to be more extendable with new fields. It also ends up being more consistent with how the data is displayed in the CLI output.

Here is an example of how it would look after this change:

Detailed results

🔴 operation-operationId-unique

Every operation must have unique "operationId".

Line Path
52 paths./pet.put.operationId

🔴 ibm-no-array-responses

Operations should not return an array as the top-level structure of a response

Line Path
96 paths./pet/find_by_status.get.responses.200.content.application/xml.schema
103 paths./pet/find_by_status.get.responses.200.content.application/json.schema

🔴 no-$ref-siblings

$ref must not be placed next to any other properties

Line Path
184 components.schemas.Pet.properties.category.description

🟠 ibm-openapi-tags-used

A tag is defined but never used

Line Path Details
22 tags.1 store
24 tags.2 user

🟠 ibm-response-status-codes

Operation responses should include at least one success status code (2xx)

Line Path
40 paths./pet.post.responses
56 paths./pet.put.responses

🟠 ibm-request-and-response-content

Request bodies and non-204 responses should define a content object

Line Path
41 paths./pet.post.responses.405
57 paths./pet.put.responses.400
59 paths./pet.put.responses.404
61 paths./pet.put.responses.405
109 paths./pet/find_by_status.get.responses.400

🟠 ibm-operationid-naming-convention

operationIds should follow naming convention

Line Path Details
52 paths./pet.put.operationId operationId verb should be replace

🟠 ibm-schema-description

Schemas should have a non-empty description

Line Path
96 paths./pet/find_by_status.get.responses.200.content.application/xml.schema
103 paths./pet/find_by_status.get.responses.200.content.application/json.schema

🟠 ibm-success-response-example

Response bodies should include an example response

Line Path
102 paths./pet/find_by_status.get.responses.200.content.application/json

🟠 ibm-securityschemes

A security scheme is defined but never used

Line Path
138 components.securitySchemes.api_key

🟠 ibm-property-description

Schema properties should have a non-empty description

Line Path
143 components.schemas.Category
146 components.schemas.Category.properties.id

🟠 ibm-string-attributes

String schemas should define property 'pattern'

Line Path
151 components.schemas.Category.properties.name
151 components.schemas.Category.properties.name
151 components.schemas.Category.properties.name
164 components.schemas.Tag.properties.name
164 components.schemas.Tag.properties.name
164 components.schemas.Tag.properties.name
185 components.schemas.Pet.properties.name
185 components.schemas.Pet.properties.name
185 components.schemas.Pet.properties.name
194 components.schemas.Pet.properties.photo_urls.items
194 components.schemas.Pet.properties.photo_urls.items
194 components.schemas.Pet.properties.photo_urls.items

🟠 oas3-unused-component

Potentially unused component has been detected.

Line Path
210 components.schemas.UnusedString

@dpopp07 dpopp07 requested review from hudlow, pyrooka and padamstx April 10, 2025 19:09
@dpopp07 dpopp07 force-pushed the dp/reformat-markdown-ouput branch from 0a05984 to ec65191 Compare April 10, 2025 21:26
@dpopp07 dpopp07 marked this pull request as draft April 21, 2025 17:13
Rather than generating one big table, with lots of wide columns, this
generates one section, including a single table, per rule, to remove
redundant information and efficiently display all the data associated
with the violations of a given rule.

Signed-off-by: Dustin Popp <[email protected]>
@dpopp07 dpopp07 force-pushed the dp/reformat-markdown-ouput branch from ec65191 to beb0692 Compare April 29, 2025 22:37
@pyrooka pyrooka removed their request for review May 5, 2025 09:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant