Reunite
It looks good, and is informative
rule/operation-id-snake-case:
subject:
type: Operation
property: operationId
message: Operation ID must use snake_case style.
assertions:
casing: snake_case
rule/tag-description-max-length:
subject:
type: Tag
property: description
message: Tag description must be less than 30 characters.
assertions:
maxLength: 29
rule/parameter-require-example:
subject:
type: Parameter
message: Request parameters must have either example or examples field.
assertions:
requireAny:
- example
- examples
rule/response-description-not-generic:
subject:
type: Response
property: description
message: Response descriptions must be specific and informative, not generic phrases like 'Successful operation'.
assertions:
notPattern: /Successful operation/iCool training, easy and the rules work well!
Nothing, everything was well documented
(AI Generated)
Security inconsistency GET /orders/{orderId} has security: [] (public), while GET /orders requires OAuth2 (orders:read). GET /order-items requires OAuth2, but GET /orders/{orderId} doesn't. Impact: Inconsistent access control; a single order is public while the list requires auth.
Missing filter format documentation The Filter parameter says "This field requires a special format" but doesn't document it. Example shows orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7, but the format isn't explained. Impact: Users can't reliably construct filter values.
Vague search parameter description The Search parameter description is just "Search." Impact: Unclear what fields are searched or how it works.
Data inconsistency in examples Line 87: category: beverage (singular) Line 106: category: beverages (plural) Schema enum (line 813): only allows beverage (singular) Impact: The plural example violates the schema and is misleading.
Missing response codes Some operations may be missing appropriate error responses (e.g., 422 Unprocessable Entity for validation errors).
Incomplete parameter documentation Filter format not documented despite being "special". Search behavior not documented.